Skip to content

Instantly share code, notes, and snippets.

@andreastt andreastt/ Secret
Last active Jun 22, 2016

What would you like to do?


Prototype of a distributed bug tracking system backed by git.

Bugs, or issues, are stored together with a program’s source code in an in-tree branch called issues in human-readable format; indexed and searchable through git-issues. Conflict resolution favours a “both sides win” strategy to minimise impact of mid-air collisions.

git-issue sets out to innovate on the traditional client-server relationship that has served bug tracking well over the last two decades. Instead of using a create-read-update-delete database that require data locks to prevent data races, it aims to employ conflict resolution through three-way merges, meaning each developer has immediate offline access to the entire bug database.

By providing the repository and issue reports together under distributed version control, git-issue facilitates tighter integration of code and issues.

As is the case with changes in a git repository, git-issue provides a staging area that is an intermediary area where issues can be formatted, changed, and reviewed before “committing” them. This means you can operate on multiple issue reports concurrently.

When viewing—or showing—an issue, they are annotated with commit messages they are referenced in. This allows you to track changes related to an issue directly from the comfort of a git client. git-issue comes coupled with a built-in web server serving a traditional bug tracking user interface for easier tracking and overview. This lets you navigate source code changes and jump between changes related to issues.

Issue metadata

Issues have the following metadata associated with them:

The unique descriptor of this issue. Notably, git-issues does not use bug numbers, but a unique SHA-1 value. This value is referred to throughout as an issue.
Short description of the issue.
Summary of the issue, reproduction steps, affected systems, &c.
Free-text labels.
Email of the person assigned to the issue.


git issue add

To file a new issue, you may edit one of the predefined templates in your favourite editor:

% git issue add

Most metadata fields can be prepopulated with flags, much like git-send-email:

% git issue add --label foo --label bar

git issue show

Displaying an issue works much like showing a normal git object through git-show:

% git issue show ISSUE

Where ISSUE is the SHA-1 of the issue you want to show.

You can output the issue in different formats:

% git issue show ISSUE --format json

git issue serve

To interact with, search, and show issues in a web browser you can serve the built-in HTTPD in a local port on your system:

% git issue serve
Serving on http://localhost:6666/

Or on a custom port:

# git issue serve
Serving on

Conflict resolution

As issues are distributed flat files conflict resolution is important.

Comments to issues are by definition never conflicting unless two remotes have edited the same public comment and not synchronised in between. In the happy path scenario where comments are write-only, additional comments will append by merge timestamp rather than be considered as mid-air collisions as they are in certain other bug tracking software.

Resolution of conflicts in the updating of issue descriptions, titles, assignee, and so forth is more challenging, and will need to be manually resolved by the user. Labels could be treated a a special case where additions and removals are discounted, and only changes to existing phrases or words could be considered conflicting (think git diff -p word-diff or word-by-word diffs).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.