0
@@ -26,40 +26,30 @@ keeping by the `git-issues` script.
0
If you were to checkout this branch, you'd find a set of top-level
0
directories, each giving the first two characters of a Git object name (hash
0
id). This mirrors the way that loose objects are organized within
0
-`.git/objects`. In each of these directories will be another set of
0
-directories, this time spelling out the remaining 38 characters of each
0
-issue's unique object name. No matter what is done with an issue, this
0
-reference to it never changes.
0
+`.git/objects`. In each of these directories is another set of directories,
0
+this time spelling out the remaining 38 characters of each issue's unique
0
+object name. No matter what is done with an issue, this reference to it never
0
In each each uniquely named issue directory may be found one or more files of
0
-The info file is unchanging after an issue is created, and it's the
0
-contents of this file which identify the object name of the issue. It
0
+The data file changes throughout the history of an issue, even though the
0
+object name for the issue (it's 40-byte hash) is always used from the time of
0
+creation onward. Issues are mutable, after all.
0
-1. A numerical timestamp indicating when the issue was created.
0
+The file is in a very straightforward form of XML, where each data string
0
+occupies its own line to facilitate merging. Note that for any XML haters out
0
+there, you'll never have to look at this data. I just picked XML because it's
0
+(a) relatively future-proof, and (b) very merge-friendly.
0
-2. The name and e-mail address of the person who created the issue with
0
- git-issues. This is not necessarily the original submitter of the
0
- issue, nor is it necessarily the person the issue is assigned to. In
0
- fact, this person may have no meaningful connection with the issue at
0
- all, they are simply the original author of its title.
0
+The data contained maps directly on to what you see from the `git issues show`
0
+command. Use `git issues dump` to view the XML directly, or for importing
0
+into a higher-level script.
0
-3. The issue's original title.
0
-At any point in the future there may be a new title or author assigned
0
-to an issue, but these three original details are kept as the
0
-"signature" of the issue itself and are left unchanged.
0
-This file contains a series of keys and values (in the form of "Key:
0
-Value"), which indicate the current state of the issue. Any of these
0
-are editable, and it is these details which get displayed to the user
0
-through the various `git-issues` commands:
0
+Here's some of the data this file tracks:
0
@@ -79,53 +69,44 @@ through the various `git-issues` commands:
0
* Priority: high, med, low
0
-A comment is a note attached to an issue. It cannot be changed,
0
-although it can be deleted and superceded by a revised version. It has
0
-1. The first line is a timestamp indicating when the comment was made.
0
-2. The second line is the name and e-mail of the author of the comment,
0
- just like the `info` file above.
0
+## `comment_[ISO_TIMESTAMP]_[HASH].xml`
0
-3. The third line is a comma-separated list of attachments hashes
0
- associated with this comment, or a blank line if none.
0
+A comment is a note attached to an issue. This XML file records:
0
-4. The fourth and remaining lines of the file make up the body of the
0
- comment. If the comment has no body at all (if this is just an
0
- attached, then there is no fourth line).
0
+ * When the comment was created
0
+ * When the comment was last edited
0
+ * The author of the comment
0
+ * The text of the comment itself
0
+ * Any attachments associated with the comment.
0
-An attachment is a text or binary file which has been linked to an
0
-issue. It's name is the same as the blob that records its contents.
0
-There must always be one or more comments that refer to the attachment,
0
-otherwise the system is free to delete it.
0
+An attachment is a text or binary file which has been linked to an issue.
0
+It's name is the same as the filename it's created under. There must always
0
+be one or more comments that refer to the attachment, otherwise the system is
0
-## Top-level `project
` file
0
+## Top-level `project
.xml` file
0
Also, at the top-level of the `issues` branch is a file which contains
0
-information relating to the whole project. The file is named `project` and
0
-contains the following key values pairs in the form of "Key: Value". Most
0
-keys can repeat in order to specify multiple values:
0
- * Component: TITLE = NAME <E-MAIL>
0
-Each of these key/value pairs identifies a legal value for the given field.
0
-Only the "Tags" field is freely assignable to any value; all other fields must
0
-match one of the settings in the `project` file.
0
-The Component field can have a default "Owner". This is the person who gets
0
-notified of your issue when they pull the new issue down from the public
0
+information relating to the whole project. The file is named `project.xml`
0
+and contains the following information.
0
+Each of these identifies a legal set of values for the given field. Only the
0
+"Tags" field is freely assignable to any value; all other fields must match
0
+one of the settings in the `project` file.
0
+The Component field can also specify default "Owners" for each component.
0
+This is the person (or people) who get notified automatically about changes in
0
+the issue whenever they pull the new issue down from the public repository.
0
Lastly, the Version field must match an existing tag name.
) is private.
Comments
No one has commented yet.