I’m pleased to announce the first release of gliss, a tool to make it easier to track lightweight inline annotations in your git repositories. gliss is available as source code or as a Ruby gem.
Consider the following things you might want to do if you could put metadata in your commit messages:
- You’d like to link commits to the bug-tracking tickets that they addressed.
- You’d like to identify commits that other developers have signaled might require a release note (or, worse yet, introduce a backwards-compatibility problem).
- You’re working on a private branch and you’d like to mark some commits for later redaction or revision.
If you’re willing to adopt a simple, flexible microformat for metadata annotations in commit messages, you can write annotations expressing all of these and more, and then use the gliss tool to identify all of the annotations (optionally of a certain kind) in a range of commits (or in the difference between two trees). We’ll begin by introducing the format for these annotations.
A gliss annotation is called a gloss and has two parts: a tag, and (optionally) some text. To put a gloss in your commit message, simply begin a line with three identical characters, which we’ll call the tag delimiter, followed by a tag name, which can be any string of characters that doesn’t start with a dash or contain the tag delimiter, and then the tag delimiter again. Examples include ---FRED---, ===BARNEY===, and ***WILMA***. gliss will recognize lines that contain gloss tags and process them. Any additional text on the same line as the gloss tag will be treated as the beginning of the gloss text.
A gloss can contain more than one line; simply indent the first line after the line containing the gloss tag, and this line becomes a continuation line: any text after the indent will be appended to the gloss text. Similarly, any line after a continuation line will be a continuation line if it is at least as indented as the first continuation line of its gloss. (Currently, the gliss tool strips extra whitespace from continuation lines before outputting them; in a future release of gliss, glosses whose tag begins with a dash will be outputted with whitespace and formatting preserved.)
As an example, consider this commit message from the gliss repository, which contains two glosses, both tagged @EXAMPLE. The first is contained on a single line. The second contains multiple continuation lines; its ends with the first non-indented line.
To inspect these messages with the gliss tool, make sure you have gliss installed and the gliss repository checked out locally. You can then run gliss 2ce2b3c2 master from within the gliss repository directory, and it will show you all of the glosses in commits that are ancestors of master but are not ancestors of 2ce2b3c2. (You can omit master from the command-line; it’s the default.) The output will look something like this:
172863f7 (@EXAMPLE)
This is an example gliss message, tagged @EXAMPLE.
172863f7 (@EXAMPLE)
This is another example gliss message, that spans multiple lines.
As long as each line has at least the same amount of indentation
as the first line after the tag, messages can span one or many lines.That’s it.
The gliss tool also supports some options, notably to display only glosses with certain tags. Try gliss -h for some brief documentation overview.
I wrote gliss because I intend to use it, but I hope you find it useful, too. Please don’t hesitate to send in feedback or bug reports.