Page History

Turn Off History

Gliss is a tool for extracting specially-formatted tagged comments from git histories. It is designed to provide a sane workflow around extracting version history, ticket, and backwards-incompatibility information from a stream of commits.

This page is intended to get you started with gliss as quickly as possible; you may want to see this short article for more details.

Annotating your commits

A gliss gloss is a simple tagged annotation in a commit message. The basic format of a gliss gloss is three identical characters on a line by themselves, followed by a tag name, followed by the same three identical characters that opened the line, and then the tag text; for example: 

  ===FOO=== This is a gloss tagged FOO

If you need to extend comment text beyond one line, simply indent the second line and ensure that every subsequent line is at least as indented as the second line. Here's what that would look like: 

  ===FOO=== Here's a slightly longer-winded
    gloss tagged FOO.

Such a gloss will end before the beginning of the first line that is not at least as indented as the second line.

Useful tags

Here are some useful tags for your gliss glosses:

  1. GT, followed by a ticket number (starting with a pound so gittrac will recognize it), which indicates that this commit is related to a particular ticket.
  2. GT:Fixed, followed by a ticket number (again, starting with a pound); this implies GT and indicates that this commit resolves a particular ticket.
  3. UpgradeNote includes a description of a backwards-compatibility issue introduced by this commit (e.g. "This commit changes the wire protocol for the pony server.")
  4. VersionHistory includes a version history entry related to this commit.

Installing a commit message template

You may find it helpful to install a git commit message template, so that some basic gliss glosses are right in front of you as you're editing the commit message. You can do this with git options. First, copy the following text to a file in your home directory (call it something like .glisscommittemplate): 

  # To use any of these glosses in your commit message, uncomment
  # the initial # and edit the gloss text as appropriate.
  #
  #===GT=== #1234
  #===GT:Fixed=== #1234
  #===VersionHistory===
  #===UpgradeNote===

Then, tell git where to find this template: 

  git config --global commit.template ~/.glisscommittemplate

(Use --global or not depending on whether you'd rather opt-out of this template for individual repositories or opt-in per repository.)

Installing gliss

The easiest way to install gliss is to use the RubyGem package. You may need to use the --user-install option to gem install or run as root.

Inspecting glosses

The basic way to use gliss is to give it two branch names, like gliss V7_5_4 V7_5_5. It will find all of the glosses in commit messages associated with commits that are reachable from V7_5_5 but not V7_5_4. There are other options, too; run gliss --help for more information.