{link: http://github.com/willb/gliss 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 {link: http://chapeau.freevariable.com/2011/01/grepping-for-git-glosses-with-gliss.html this short article} and {link: http://chapeau.freevariable.com/2011/07/gliss-020-release-and-a-gliss-example.html this example} for more details.

{section:  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 at the beginning of a line, 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.

Note that it is best to place glosses after the main content of your commit message, since git treats the first line of a commit message as a summary.  A clear single sentence of prose almost always provides a better summary of a commit than a single gloss!

{section:  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.
1:  =GT:Fixed=, followed by a ticket number (again, starting with a pound); this implies =GT= and indicates that this commit resolves a particular ticket.
1:  =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.")
1:  =VersionHistory=, a summary of the state of the version history for this item. Used to communicate with the wrangler

{section: VersionHistory glosses, AKA helping the wrangler.}

Glosses with the tag ===VersionHistory=== are intended make the wrangler's job easier.  Please make sure to include the ticket number somewhere in the commit message for commits that have {quote: VersionHistory} glosses.  The text following the {quote: VersionHistory} tag is intended to help the wrangler verify the completeness of the version history.  It is _not_ a substitute for actually editing the version history tex file.

It would be helpful to the wrangler to indicate when a commit does not require any version history, or when the version history has already been completed.

{section:  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.
  # See https://condor-wiki.cs.wisc.edu/index.cgi/wiki?p=GlissTool
  #
  #===GT=== #1234
  #===GT:Fixed=== #1234
  #===VersionHistory===
  #===VersionHistory:None===
  #===VersionHistory:Complete===
  #===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.)

{section:  Installing gliss}

The easiest way to install gliss is to use the {link: http://rubygems.org/gems/gliss RubyGem} package.  You may need to use the =--user-install= option to =gem install= or run as root.  In order to install the gem package, though, you'll need some prerequisites installed first:  =ruby= and the =rubygems= package manager itself.  Some distribution-specific hints follow.

If you're on a fairly recent Fedora release (or RHEL 6/CentOS 6), you should be able to simply =yum install ruby rubygems= and get all of the necessary packages.  If you're on an older RHEL or RHEL-derived distribution (like RHEL 5), then =rubygems=, like =git=, will be in EPEL.  {link: http://fedoraproject.org/wiki/EPEL#How_can_I_use_these_extra_packages.3F EPEL} is a set of extra packages for Red Hat Enterprise Linux and derived distributions; you can get access to the EPEL repositories by installing the right =epel-release= package.  For RHEL 5, for example, you'd do this:

    rpm -ihv http://download.fedoraproject.org/pub/epel/5/i386/epel-release-5-4.noarch.rpm

If you're on a Mac, =ruby= and =rubygems= probably shipped with your operating system.

{section:  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.