This script implements distributed bug tracking for Git repositories. It
replicates the functionality of packages like ticgit, but does so in the form
of a more standalone Python script. You can check this script in along with
your project in order to ensure that all contributors are able to view the bug
database using the same version of the script that you used to create them.
git issues new [-m "Comment for the issue"] "Issue title" git issues list # show all issues git issues show OFFSET|HASH git issues push # submit your issues via repo or e-mail git issues pull # merge in the latest issues git issues close ID # mark an issue as closed
The data for
git-issues is kept in a separate branch configured through
the issues.branch option. By default the branch is named
user is never intended to checkout this branch, it’s used solely for record
keeping by the
If you were to checkout this branch, you’d find a set of top-level
directories, each giving the first two characters of a Git object name (hash
id). This mirrors the way that loose objects are organized within
.git/objects. In each of these directories is another set of directories,
this time spelling out the remaining 38 characters of each issue’s unique
object name. No matter what is done with an issue, this reference to it never
In each each uniquely named issue directory may be found one or more files of
the following form:
The data file changes throughout the history of an issue, even though the
object name for the issue (it’s 40-byte hash) is always used from the time of
creation onward. Issues are mutable, after all.
The file is in a very straightforward form of XML, where each data string
occupies its own line to facilitate merging. Note that for any XML haters out
there, you’ll never have to look at this data. I just picked XML because it’s
(a) relatively future-proof, and (b) very merge-friendly.
The data contained maps directly on to what you see from the
git issues show
git issues dump to view the XML directly, or for importing
into a higher-level script.
Here’s some of the data this file tracks:
- Author: Who wrote the actual issue record
- Reporter: Who reported this issue
- Owner: Who is responsible for closure
- Assigned: Who is it presently assigned to
- Cc: Who else wants to know about it
- Status: new, open, pending, deferred, closed
- Resolution: fixed, wontfix, dup
- Type: defect, feature, docs
- Severity: blocker, critical, major, minor, cosmetic
- Priority: high, med, low
A comment is a note attached to an issue. This XML file records:
- When the comment was created
- When the comment was last edited
- The author of the comment
- The text of the comment itself
- Any attachments associated with the comment.
An attachment is a text or binary file which has been linked to an issue.
It’s name is the same as the filename it’s created under. There must always
be one or more comments that refer to the attachment, otherwise the system is
free to delete it.
Also, at the top-level of the
issues branch is a file which contains
information relating to the whole project. The file is named
and contains the following information.
Each of these identifies a legal set of values for the given field. Only the
“Tags” field is freely assignable to any value; all other fields must match
one of the settings in the
The Component field can also specify default “Owners” for each component.
This is the person (or people) who get notified automatically about changes in
the issue whenever they pull the new issue down from the public repository.
Lastly, the Version field must match an existing tag name.