summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/gitver/gitver.tex
blob: dd600690402f8c067c25a2bf06b05b7f785d8510 (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
%!TEX options = --shell-escape
%
% This command causes LatexTools for SublimeText to compile in shell escape mode. 
%
% If you're not using LatexTools to compile, you will need to enable shell
% escape on your editor some other way

\documentclass[a4paper]{ltxdoc}

\usepackage{fancyhdr}
\pagestyle{fancy}

\usepackage{gitver}


\begin{document}

\title{\textsf{gitver} -- Git version tags \\ 
for \LaTeX{} projects}
\author{Charles Baynham}
\date{2019/02/06 (v\,1.0)}
\MaintainedBy{%
	This file is maintained by Charles Baynham.\\%
	Bug reports can be opened at\\%
	\url{https://github.com/charlesbaynham/gitver}.
}

\maketitle

\section{Introduction}

The \textsf{gitver} package gets a description of the current git version of this
document and store it in a command |\gitVer|. If memoir or fancyhdr are in use, it
will also add this to the document footers unless the option "noheader" is
passed.

It also defines a command |\versionBox| which outputs a box containing the
version and date of compilation. 

For this to work, you must have git installed and available on the command
line, this document must be part of a git repository, and latex must be
running in "shell escape" mode. This can be enabled by passing \textsf{--shell-escape}
on the command line when compiling your docuemnt, or will be available in the
options of whatever GUI you're using (try Googling).

Note that it's a good idea to tell git to ignore all the latex auxilary files,
otherwise your version will always be ``dirty''. Try the \textsf{.gitignore} file from
\url{https://www.gitignore.io/api/latex} if you don't already have
one.

The package is released ``as is'' with no warranty under the LaTeX Project Public
License, version 1.3.

\section{Usage}

\subsection{Macros} % (fold)
\label{sub:macros}

% subsection macros (end)

\DescribeMacro{\gitVer}
%
The main point of this package, the command |\gitVer| prints a string of text describing the current revision of this git repository. Use like so:
\begin{quote}
	The current version of this repository is ``|\gitVer{}|''.
\end{quote}
which compiles to
\begin{quote}
	The current version of this repository is ``\gitVer{}''.
\end{quote}

\DescribeMacro{\versionBox}
Alternatively, you can use a |\versionBox|, most commonly in the footer:
\begin{quote}
	|\versionBox{}|
\end{quote}
%
gives the output:
\vspace{3mm}

\versionBox{}

\subsection{Footers} % (fold)
\label{sub:footers}

By default, \textsf{gitver} will try to place a |\versionBox| into the footer of your document. If you're using the |memoir| class or the |fancyhdr| package, this will happen automatically. This document has these footers enabled: have a look at the bottom of this page for an example. 

\DescribeMacro{noheader}
You can disable the headers by adding the option |noheader| to the package call. 

If you include |gitver| without either of |memoir| or |fancyhdr| loaded, it will complain. To suppress this complaint, pass the |noheader| option. 

To customise the header / footer behavior, pass |noheader| and then use a combination of |\versionBox| and |\gitVer| to make your own headers/footers. 

% subsection footers (end)

\subsection{Metadata} % (fold)
\label{sub:metadata}

\DescribeMacro{nopdfinfo}
By default, this package also adds the git tag to to pdf document's metadata under the subject field. To disable this behaviour, pass the option |nopdfinfo|. 

% subsection metadata (end)

\end{document}