A pre-announcement

About 2½ years ago, I uploaded version 1 of gitinfo. Since then, I have received many emails suggesting features and asking for advice, but until now I just hadn’t had the time to act on them. Over the past few days, however, I’ve returned to those emails, and the end result is gitinfo2, which I’ve just submitted to CTAN.

gitinfo2 — the package

The purpose of gitinfo2, in a nutshell, is to give authors access to (selected) metadata from the git DVCS repository in which they are working on their documents. Through curiously-constructed hooks, git records certain key values when files are checked out, committed, or merged, and gitinfo2 makes those values available as document commands.

Since the values, and the file(s) in which they are recorded, have changed to allow new and better things, this is a new package, since updating the old would have condemned existing users to migrate their work to the new format.

The package lives here on GitHub, and here on CTAN. And in due course it should appear in your favourite TeX distribution.

As well as additional useful document commands, there are four main improvements and additions in gitinfo2, and I’ll describe these below: improved access to git tag information for sensible user-defined Version and Release numbers; watermarking with metadata; the ability to maintain documents in any part of the repository without having to make special arrangements; and, for memoir users, a cleaner way of setting metadata in the page footer.

Access to git tag data

gitinfo2 recognises git tags which begin with a digit, and contain a decimal point (such as ‘2.1-beta’), as Release names. It searches the ancestors of the current branch for them, and makes the first one found available as \gitRel (and a few others).

As before, it also recognises decimal tags at the head of the current branch as Version numbers, and makes them available as \gitVtag (and a few others).

All the tags at the current branch head are collected as a comma-separated list, available as \gitTags.

Metadata watermarking

If instructed, gitinfo2 can place a watermark at the very foot of each page, centred on the paper (that is, unrelated to the Form of the Book, because it’s not really for publication). Here’s a sample. The watermark is in the magenta box (which is not part of it), and lies below the normal page footer (also generated by gitinfo2 with help from memoir). Before I hear snorts of typographical indignation, remember that the watermark is centered on the paper, not the textblock:

One of three package options may be used to generate the watermark: [mark] is unconditional; [markifdraft] adds the watermark only for documents marked as draft in the options to the document class; and [markifdirty] adds the watermark if the repository working copy contained uncommitted changes after the last checkout, commit or merge.

Documents in any directory

Metadata from your git repository is written into a file called githeadInfo.gin. Formerly, this file had to live in the same directory as the document master TeX file, and if you wanted to place it somewhere other than in the root of the repository, you were obliged to make specific changes to the git hook scripts.

No more! gitHeadInfo.gin now lives in the .git directory at the root of the repository, and gitinfo2 now goes and sniffs it out, wherever the document may be. Well, within reason; if your document lives in a directory nested more than four levels below the root, gitinfo2 can’t find it unless you specify the package option [maxdepth=n].

Page styles for memoir users

In gitinfo, memoir users could specify that they wanted the package to alter the standard memoir page styles (plain, ruled, and headings) to incorporate revision information.

gitinfo2 has cleaned this up: the standard page styles are no longer changed, and the package provides three new page styles (giplain, giruled, and giheadings) which can be used in their place as and when the author requires.

Summing up

I’m really pleased with this, especially the new features. But I’m not qualified to judge, so I hope you’ll play with it, clone it and tinker at it, and send me feedback here, by email, or on TeX’n’Friends.

Brent Longborough