gitinfo2: LaTeX and git join forces

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:

Watermark example output

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

6 thoughts

  1. I haven’t used gitinfo yet, but I’m looking forward to trying out gitinfo2. I think you’re right on the money: there is a lot of potential in facilitating access to Git metadata from within TeX documents. Have you considered implementing some automatic graphing capabilities? Wouldn’t it be nice if you could specify a range of the repo’s DAG and you’d get a nice (TikZ?) diagram showing you the repo’s history over that range? I’m thinking of an automated version of http://tex.stackexchange.com/a/156501/21891. I hope I’ll find the time to look into your source code, and perhaps contribute to it, at some stage. Keep up the good work!

  2. Thanks Brent! I think this is really cool, and works great! I see the

    .git/gitHeadInfo.gin

    only gets updated on a

    checkout

    . Should the

    post-commit

    script not maybe change to

    pre-commit

    as there are no samples for the

    post-commit

    ?

    1. Nope, trying to copy the scripts under different names, but I can only get it to update the

      gitHeadInfo.gin

      file if I issue the comment

      git checkout

      (which is not typically what I would do after a commit or push. I’ll play around and see if I can get to to work. If someone has an idea, please let me know.

  3. Oops, don’t worry… I was just an idiot. I was (mistakenly) under the impression that copying a file,

    .git/hooks/post-checkout

    as per the LaTeX documentation, to

    post-commit

    and

    post-merge

    will copy the file permissions along with it. It doesn’t…

    So once I fixed that, it works even more perfectly 😉

Leave a Reply to Johan W. Joubert Cancel reply

Your email address will not be published. Required fields are marked *