2014/12/02

LaTeX で git のメタ情報を使うパッケージ

2014年現在、「自動組版のためのPDF生成器である」と豪語できるツールは、どうやらまだまだ (La)TeX だけという状況っぽいです(異論は認める宗教戦争前夜)。 しかし、自動組版に使えると豪語するからには、 git のメタデータくらいは気軽に出力できないと困ります。にもかかわらず、どうも CATN にはこれといった便利パッケージが見当たらない†1。その愚痴を TeX & LaTeX Advent Calendar 2014 の2日目の記事としてぶつけます。(1日は ZR さん、明日3日は doraTeX さんです。大物に挟まれてつらい)

ところで、今週末の12/6(土)は、自動組版とバージョン管理の可能性を模索しようという「版管理+自動組版」という集まりがあります。 ものすごく楽しみです。 閑話休題。

さっそくですが、 git のメタ情報を (La)TeX のドキュメント中で利用するためのパッケージとしては、 gitinfo2vc といったものがあるようです。 いずれも、たとえば自分のドキュメントに git のコミットハッシュの文字列を含めたかったら、\gitHash(gitinfo2) とか \GITHash(vc)といった引数なしのコマンドを自分のドキュメントの中で指定して使う仕組みです。分かりやすいですね。

しかし、ここで厄介なのが、これらのパッケージのインストールと設定です。 いずれも TeX Live 2014 に入っているので、プリアンブルで \usepackage するだけで使えると実にうれしいのですが、残念なことにそんな安直な使い方をさせてくれません。事前に外部のスクリプトを自分で設定する必要があります。

vc パッケージの場合は、毎回ドキュメントをコンパイルする前に vc-git.awk というスクリプトを実行し、vc.tex というメタ情報が入ったファイルを生成して、このファイルをドキュメントから \include するという仕組みになっています。 なので、このスクリプトを手動で実行したり、 Makefile に記述しておいたり、 \write18 を使って vc-git.awk をドキュメントのコンパイル時に実行したりする必要があります。公式のドキュメントで説明されているのは \write18 を使う方法です。

gitinfo2 のほうは、 git に特化しているだけあって少しだけ先進的で、 git のフックスクリプトの機能を利用する仕組みになっています。 具体的には、

  • 特定のファイルに git log HEAD を出力するだけのコマンドシェルスクリプトを、ユーザが自分の .git/hooks ディレクトリに設置する
  • その特定のファイルをドキュメント中で \input で読み込んでおく
という具合です。 でもこれだと、GitHub をポーリングして CI を回している環境ではちょっと使いにくい(コミットフックで出力される特定のファイルをバージョン管理化におけばいいのですが、なんかいやだ)。

仕方がないので、自分ではこれらのパッケージを使っていません。 代わりに、 git のコミットハッシュを \write18 で取得するだけという、超低機能な自前コマンドを使っています。 これをプリアンブルに仕込んでおけば、 git の短縮版コミットハッシュの文字列が \gitRevision という引数なしのコマンドで得られます。

\immediate\write18{git show HEAD --pretty="\@percentchar h" -s > revision.tmp}
\def\gitRevision{\input{revision.tmp}}

さらに、みようみまねで buildinfo.sty という LaTeX2e 用のパッケージにしてみました。

\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{buildinfo}[2014/12/06 provides git hash as a command]
\RequirePackage{etoolbox}
\RequirePackage{kvoptions}
\SetupKeyvalOptions{family=buildinfo, prefix=buildinfo@}
\DeclareBoolOption{long}
\ProcessKeyvalOptions*
\immediate\write18{date +\@percentchar c  > build.tmp}
\ifbool{buildinfo@long}
  {\immediate\write18{git show HEAD --pretty="\@percentchar H" -s > revision.tmp}}
  {\immediate\write18{git show HEAD --pretty="\@percentchar h" -s > revision.tmp}}
\newcommand{\buildDate}{\input{build.tmp}}
\newcommand{\gitRevision}{\input{revision.tmp}}

\usepackage{buildinfo} すれば、 短縮版のコミットハッシュ文字列に展開される \gitRevision コマンド(\usepackage[long]{buildinfo} とすれば40文字になる)と、 コマンド実行時の日時の文字列に展開される \buildDate コマンドが使えるようになります。


†1 思い返せば、Subversionを使っていたころにも、 svninfo というパッケージでファイル単位でしかメタ情報を扱えないことに苦慮していたことがありました。(いまや完全に git に移行したので、この問題は個人的には原理的になくなりましたが。)

No comments :