summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/gitinfo/gitinfo.tex
blob: af6f90764c7415e59d4064e10c1d5c4f9db1a8ee (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
% gitinfo.tex   
% Copyright 2011 Brent Longborough
%
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3
% of this license or (at your option) any later version.
% The latest version of this license is in
%   http://www.latex-project.org/lppl.txt
% and version 1.3 or later is part of all distributions of LaTeX
% version 2005/12/01 or later.
%
% This work has the LPPL maintenance status `maintained'.
% The Current Maintainer of this work is Brent Longborough.
%
% This work consists of these files: 
%     gitinfo.sty, gitsetinfo.sty, gitinfo.tex, gitinfo.pdf,
%     post-git-sample.txt, and gitHeadInfo.gin
% -----------------------------------------------------
\documentclass[a4paper,12pt,twoside,openany]{memoir}
\usepackage[pcount,footinfo,grumpy]{gitinfo}
\usepackage{tgpagella}
\usepackage{tgadventor}
\usepackage{fontspec}
\defaultfontfeatures{Ligatures=TeX}
\setmainfont[Numbers={Proportional,OldStyle}]{TeX Gyre Pagella}
\setsansfont[Numbers={Proportional,OldStyle}]{TeX Gyre Adventor}
\setmonofont{Consolas}
\setulmarginsandblock{0.11111\paperwidth}{0.22222\paperwidth}{*}
\setlrmarginsandblock{0.11111\paperwidth}{0.22222\paperwidth}{*}
\setheadfoot{1.2\baselineskip}{0.0849\paperwidth}
\setmarginnotes{0.125\foremargin}{0.75\foremargin}{\onelineskip}
\setheaderspaces{*}{*}{0.618}
\checkandfixthelayout[fixed]
\tightlists
\chapterstyle{bringhurst}
\pagestyle{ruled}
\settocdepth{section}
\setsecnumdepth{none}
\newcommand{\sfit}[1]{\textit{#1}}
\newcommand{\git}{\sfit{git}}
\newcommand{\tpname}{\sfit{gitinfo}}
\newcommand{\tpfname}{\textsf{gitinfo.sty}}
\newcommand{\ginname}{gitHeadInfo.gin}
\newcommand{\metaname}{\texttt{\ginname}}
% -----------------------------------------------------
\usepackage[%
	bookmarksnumbered,
	bookmarksopen,
	linktocpage,
	]{hyperref}
\hypersetup{
   pdfauthor={Brent Longborough},
   pdftitle={The gitinfo package: git metadata for LaTeX},
   pdfkeywords={git;metadata;dvcs},
}
\begin{document}
% -----------------------------------------------------
\title{%
	\Huge \tpfname\\[2ex]%
	\Large A package for accessing metadata\\from the \git\ \textsc{dvcs}
	}
\author{Brent Longborough}
\date{29th August, 2011}
\maketitle

{\centering
Version:\gitVtagn\\
}
%\vspace*{2\baselineskip}
% -----------------------------------------------------
\begingroup
\aliaspagestyle{chapter}{empty}
\setlength{\afterchapskip}{20pt}
\let\clearpage\relax
\let\chaptitlefont\Large\bfseries
\vspace*{5\baselineskip}
\tableofcontents*
\clearpage
\endgroup
% -----------------------------------------------------
\chapter{Introduction}
More and more, writers are using version control systems
to manage the progress of their works.
One popular distributed version control system commonly used today
is \git.

Among other blessings, \git provides
some useful metadata concerning the history of the developers'
work, and, in particular, about the current state of that work.

\tpname\ allows writers to incorporate some of this metadata
into their documents, to show from which point in their development
a given formatted copy was produced.

% - - - - - - - - - - - - - - - - - - - - - - - - - - -
\section{How \tpname\ works}
\begin{enumerate}
\item Whenever you commit work or check out a branch in \git,
\git\ executes a \textit{post-commit} or \textit{post-checkout hook}.
\item The \tpname\ package includes a sample hook
(placed in your \git\ hooks directory),
which extracts metadata from \git\ and writes it to a \TeX\ file,
named \metaname\ (`gin' for \textbf{g}it \textbf{in}fo).
\item When you format your document, \tpname\ reads 
\metaname\ and stores the metadada
in a series of \LaTeX\ commands.
\item You may use these commands to insert
the metadata you need at any point in the document.
\end{enumerate}

It is important to note that \tpname\ reads the metadata
with the equivalent of \texttt{\textbackslash input\{./\ginname\}}.
This is necessary to avoid possible future confusion in a
\TeX distribution where more than one package includes its
metadata in this way; but it requires that for every document which
uses \tpname, a \metaname\ must be generated in the same directory. 

If you actually want to use \tpname, then please read on.
But you may just be reading this to see whether it will be useful;
in this case,
please skip the next chapter and go on to (Using the package)
on page \pageref{ch:using}.
If you like what you see, you can come back to
read (Setup) later. 
% -----------------------------------------------------
\chapter{Setup}
\tpname\ will be installed by your favourite package or distribution manager,
but before you can start to use it,
you need to configure each of your \git\ working copies
by setting up hooks to capture the metadata.
Every document in your working copy that uses \tpname\
will need a copy of \metaname\ in the same directory.

These copies can be generated by the \git\ post-hooks,
which need to be configured once, at the start.

If you're familiar with tweaking \git, you can probably work it out for yourself.
If not, I suggest you follow these steps:

\begin{enumerate}

\item First, you need a \git\ repository and working tree.
For this example, let's suppose that the root of the working tree is in
\texttt{\textasciitilde/compsci}

\item Copy the file \texttt{post-xxx-sample.txt} as \texttt{post-checkout}
into the \git\ hooks directory in your working copy.
In our example case, you should end up with a file called
\texttt{\textasciitilde/compsci/.git/hooks/post-checkout}

\item With your favourite editor, edit the file you have just created.
Very near the start of the file, you will see two lines:
\vspace{0.5\baselineskip}

\noindent\texttt{prefixes=". test docs"\\
prefixes="."} 
\vspace{0.5\baselineskip}

The first line is an example of how you might configure for multiple
copies of \metaname; the second is the default,
and means ``the working copy root''.

If all of your documents will be kept in the root of the working copy,
you may leave this file alone.
If not, you should delete the line \verb!prefixes="."!, and edit
the other line to include the paths, relative to the working copy root,
where the documents that need access to \tpname\ are kept.

Suppose, for example, that you have a project called `compsci'.
Your working copy is \texttt{\textasciitilde/compsci}
with two paths containing documents,
\texttt{\textasciitilde/compsci/docs/essays} and
\texttt{\textasciitilde/compsci/docs/reference}.
Then you might set up the prefixes like this:
\vspace{0.5\baselineskip}

\noindent\texttt{prefixes="docs/essays docs/reference"}
\vspace{0.5\baselineskip}

which will cause copies of the metadata to be saved in
just those two directories.
In this example, it will not be accessible to documents
kept in the working copy's root
(designated by ``.'', omitted in this case),

\item Test your setup with ``git checkout master''
(or another suitable branch name).
This should generate copies of \metaname\ in the directories
you intended.

\item Now make two more copies of this file in the same directory (\texttt{hooks}), calling them
\texttt{post-commit} and \texttt{post-merge}, and you're done.
\end{enumerate}
% -----------------------------------------------------
\chapter{Using the package}
\label{ch:using}
Once you've set up your \git hooks, and done your first commit,
merge, or checkout to drive them,
you can start incorporating the metadata into your document.

The \tpname\ package is loaded in the usual way:\\[0.5\baselineskip]
\texttt{\textbackslash usepackage[$<options>$]\{gitinfo\}}

% - - - - - - - - - - - - - - - - - - - - - - - - - - -
\section{Package options}

The following options are available:\\[0.5\baselineskip]

\noindent
\begin{tabularx}{\textwidth}{@{}>{\ttfamily\bfseries}lX@{}}
grumpy&
By default, If \tpname\ can't find \metaname\ (the metadata file),
it will set all the metadata to a common value, ``(None)'',
issue a package warning, and carry on.
If the \texttt{grumpy} option is used,
this warning becomes an error, and processing stops.
\\
\texttt{missing=\textit{text}}&
If \tpname\ can't find \metaname (the metadata file),
it will normally set all the metadata to a default common value, ``(None)''.
If you wish, you can change this value to something else with, say
\texttt{missing=Help!} or \texttt{missing=\{What a mess\}}.

If you have complex needs, as in the second example,
don't forget to enclose your text in \{\}s. 
\\
footinfo&
For \sfit{memoir} users, \tpname\ will set certain items of metadata into
some memoir page footer categories,
provided that (a) the memoir package is loaded,
and (b) this option is given.

No warning is given, and no action taken,
if this parameter is used with another document class.
More detail is given below (For \textit{memoir} users).
\\
pcount&
For \sfit{memoir} users, this option, when used together with \texttt{footinfo},
will, in the affected footers, replace the folio with one of the form \textit{x/y},
where \textit{x} is the folio and \textit{y} is the page count.

No warning is given, and no action taken,
if this parameter is used with another document class,
or if the \texttt{footinfo} option is omitted.
More detail is given below (For \textit{memoir} users).
\end{tabularx}
% - - - - - - - - - - - - - - - - - - - - - - - - - - -
\clearpage
\section{The metadata}
The \git\ metadata, for the current HEAD commit,
is made available in the document
as a series of parameter-less \LaTeX commands.
Here they are:
\vspace{0.5\baselineskip}

\noindent
\begin{tabularx}{\textwidth}{@{}>{\ttfamily\bfseries\textbackslash}lX@{}}
gitAbbrevHash&
    The seven-hex-char abbreviated commit hash
\\
gitHash&
    The full 40-hex-character commit hash
\\
gitAuthorName&
    The name of the author of this commit
\\
gitAuthorEmail&
    The email address of the author of this commit
\\
gitAuthorDate&
    The date this change was committed by the author,
    in the format \textit{yyyy-mm-dd}
\\
gitAuthorIsoDate&
    The date and time this change was committed by the author,
    in ISO format, e.g. \textit{2011-08-29 13:05:54 +0100}
\\
gitAuthorUnixDate&
    The date and time this change was committed by the author,
    as a Unix timestamp, e.g \textit{1314619554}
\\
gitCommitterName&
    The name of the committer of this commit
\\
gitCommitterEmail&
    The email address of the committer of this commit
\\
gitCommitterDate&
    The date this change was committed by the committer,
    in the format \textit{yyyy-mm-dd}
\\
gitCommitterIsoDate&
    The date and time this change was committed by the committer,
    in ISO format, e.g. \textit{2011-08-29 13:05:54 +0100}
\\
gitCommitterUnixDate&
    The date and time this change was committed by the committer,
    as a Unix timestamp, e.g \textit{1314619554}
\\
gitReferences&
    A list of any \git\ references (tags, branches) associated
    with this commit, e.g. \textit{ (HEAD, master)}
\\
\end{tabularx}

\vspace{0.5\baselineskip}
Three more commands are available, but their use should be considered
experimental. \tpname\ searches the \git\ references metadata for
anything (probably a \git\ tag) that looks like a number with a decimal point.
The first such number it finds is taken as a ``Version Number''
and made available in three different formats, explained here:
\vspace{0.5\baselineskip}

\noindent
\begin{tabularx}{\textwidth}{@{}>{\ttfamily\bfseries\textbackslash}lX@{}}
gitVtag&
    The version number, without any decorations. If no version number is found,
    empty (i.e. zero width).
\\
gitVtags&
    The version number, with a leading space. If no version number is found,
    empty.
\\
gitVtagn&
    The version number, with a leading space.
    If no version number is found, a space,
    followed by the default or specified value of
    the \texttt{missing} package option.
\\
\end{tabularx}

% - - - - - - - - - - - - - - - - - - - - - - - - - - -
\section{For \sfit{memoir} users}
If you use \sfit{memoir}, \tpname provides some preset page
headers and footers for you,
if you specify the \texttt{footinfo} option as described above.

With the \texttt{footinfo} option, \tpname\ redefines
the \sfit{plain},\sfit{ruled}, and \sfit{headings} pagestyles.

For the \sfit{plain} and \sfit{ruled} pagestyles,
the folio is moved from the centre to the outer margin of the footer,
and a revision stamp is placed in the inner margin.

For the \sfit{headings} pagestyle,
the folio is moved from the outer margin of the header
to the outer margin of the footer,
and a revision stamp is placed in the inner margin of the footer.

If, as well, you use the \texttt{pcount} option, a solidus, and the page count,
are appended to the folio.

The revision stamp id generated by this fragment:
\vspace{0.5\baselineskip}

\noindent
\verb!Revision\gitVtags: \gitAbbrevHash{} (\gitAuthorDate)!
\vspace{0.5\baselineskip}

\noindent
which is set at tiny in the sans-serif font.
You can see an example in the footer of this page.
% -----------------------------------------------------
\chapter{Etc}
\section{Acknowledgements \& dependencies}

The \href{http://tex.stackexchange.com}{\TeX.SE community}
has been a constant source of help, inspiration, and amazement.
In particular, I'd like to thank
\href{http://tex.stackexchange.com/users/73/joseph-wright}{Joseph Wright},
who rescued me from the jaws of the TeX parser by explaining
\textbackslash expandafter.

I's also like to register my thanks to the owners of the packages on which
\tpname\ depends: etoobox, kvoptions, and xstring.

The failings, of course, are all mine.
% - - - - - - - - - - - - - - - - - - - - - - - - - - -
\section{Copyright \& licence}
Copyright \copyright\ 2011, Brent Longborough.

This work --- \tpname\ --- may be distributed and/or modified under the
conditions of the LaTeX Project Public License: either version 1.3
of this license, or (at your option) any later version.

The latest version of this license is at
\url{http://www.latex-project.org/lppl.txt},
and version 1.3 or later is part of all distributions of \LaTeX
version 2005/12/01 or later.

This work has the LPPL maintenance status `maintained';
the Current Maintainer of this work is Brent Longborough.

This work consists of the files 
gitinfo.sty, gitsetinfo.sty, gitinfo.tex, gitinfo.pdf,
post-git-sample.txt, and \ginname.
% - - - - - - - - - - - - - - - - - - - - - - - - - - -
\section{From the author}
Although my limitations as a \TeX nician
mean that I've implemented \tpname\ in a rather simplistic way
that needs some setup that is more complicated than I wanted,
I hope you find the package useful.
I'll be very happy to receive your comments by email.\\[\baselineskip]
Brent Longborough\\[\baselineskip]
\textsf{brent+gitinfo (at) longborough (dot) org}\\
and at \href{http://tex.stackexchange.com/users/344/brent-longborough}{\TeX.SE}
% -----------------------------------------------------
\end{document}