summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/gitinfo2
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/gitinfo2
Initial commit
Diffstat (limited to 'macros/latex/contrib/gitinfo2')
-rw-r--r--macros/latex/contrib/gitinfo2/README15
-rw-r--r--macros/latex/contrib/gitinfo2/gitHeadLocal.gin17
-rw-r--r--macros/latex/contrib/gitinfo2/gitexinfo.sty138
-rw-r--r--macros/latex/contrib/gitinfo2/gitinfo2.pdfbin0 -> 127175 bytes
-rw-r--r--macros/latex/contrib/gitinfo2/gitinfo2.sty218
-rw-r--r--macros/latex/contrib/gitinfo2/gitinfo2.tex992
-rw-r--r--macros/latex/contrib/gitinfo2/gitinfotest.tex38
-rw-r--r--macros/latex/contrib/gitinfo2/post-xxx-sample.txt31
8 files changed, 1449 insertions, 0 deletions
diff --git a/macros/latex/contrib/gitinfo2/README b/macros/latex/contrib/gitinfo2/README
new file mode 100644
index 0000000000..dac9b82294
--- /dev/null
+++ b/macros/latex/contrib/gitinfo2/README
@@ -0,0 +1,15 @@
+ The `gitinfo2' package allows version control metadata to be
+incorporated into LaTeX documents; the metadata is obtained from the
+git distributed version control system.
+ For `memoir' users, the package provides additional page styles
+(headers and footers) with selected metadata.
+
+ gitinfo2 is licenced under the LPPL. For more details,
+please see the accompanying manual: gitinfo2.pdf.
+
+Change History
+~~~~~~~~~~~~~~
+
+Current Release: 2.0.7 2015-11-22
+
+Please see gitinfo2.pdf in the package documentation directory
diff --git a/macros/latex/contrib/gitinfo2/gitHeadLocal.gin b/macros/latex/contrib/gitinfo2/gitHeadLocal.gin
new file mode 100644
index 0000000000..6ef40822df
--- /dev/null
+++ b/macros/latex/contrib/gitinfo2/gitHeadLocal.gin
@@ -0,0 +1,17 @@
+\usepackage[%
+ shash={10541bd},
+ lhash={10541bd1db148ba538c521d4168a9bdca89f37cd},
+ authname={Brent Longborough},
+ authemail={brent+ctancontrib@longborough.org},
+ authsdate={2015-11-20},
+ authidate={2015-11-20 21:17:46 +0000},
+ authudate={1448054266},
+ commname={Brent Longborough},
+ commemail={brent+ctancontrib@longborough.org},
+ commsdate={2015-11-20},
+ commidate={2015-11-20 21:17:46 +0000},
+ commudate={1448054266},
+ refnames={ (HEAD -> CTAN, develop)},
+ firsttagdescribe={2.0.7-1-g10541bd},
+ reltag={2.0.7-1-g10541bd}
+ ]{gitexinfo} \ No newline at end of file
diff --git a/macros/latex/contrib/gitinfo2/gitexinfo.sty b/macros/latex/contrib/gitinfo2/gitexinfo.sty
new file mode 100644
index 0000000000..0f80141185
--- /dev/null
+++ b/macros/latex/contrib/gitinfo2/gitexinfo.sty
@@ -0,0 +1,138 @@
+% gitexinfo.sty
+% Copyright 2015 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:
+% gitinfo2.sty, gitexinfo.sty, gitinfo2.tex, gitinfo2.pdf,
+% gitinfo2test.tex, post-xxx-sample.txt,
+% and gitHeadLocal.gin
+% -----------------------------------------------------
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesPackage{gitexinfo}[2015/11/22 v2.0.7 Auxiliary package for gitinfo2]
+\SetupKeyvalOptions{family=gitinfo,prefix=gitInf@}
+\DeclareStringOption{shash}
+\DeclareStringOption{lhash}
+\DeclareStringOption{authname}
+\DeclareStringOption{authemail}
+\DeclareStringOption{authsdate}
+\DeclareStringOption{authidate}
+\DeclareStringOption{authudate}
+\DeclareStringOption{commname}
+\DeclareStringOption{commemail}
+\DeclareStringOption{commsdate}
+\DeclareStringOption{commidate}
+\DeclareStringOption{commudate}
+\DeclareStringOption{refnames}
+\DeclareStringOption{firsttagdescribe}
+\DeclareStringOption{reltag}
+\ProcessKeyvalOptions*
+\renewcommand{\gitAbbrevHash}{\gitInf@shash}
+\renewcommand{\gitHash}{\gitInf@lhash}
+\renewcommand{\gitAuthorName}{\detokenize\expandafter{\gitInf@authname}}
+\renewcommand{\gitAuthorEmail}{\gitWrapEmail{\gitInf@authemail}}
+\renewcommand{\gitAuthorDate}{\gitInf@authsdate}
+\renewcommand{\gitAuthorIsoDate}{\gitInf@authidate}
+\renewcommand{\gitAuthorUnixDate}{\gitInf@authudate}
+\renewcommand{\gitCommitterName}{\detokenize\expandafter{\gitInf@commname}}
+\renewcommand{\gitCommitterEmail}{\gitWrapEmail{\gitInf@commemail}}
+\renewcommand{\gitCommitterDate}{\gitInf@commsdate}
+\renewcommand{\gitCommitterIsoDate}{\gitInf@commidate}
+\renewcommand{\gitCommitterUnixDate}{\gitInf@commudate}
+\renewcommand{\gitFirstTagDescribe}{\detokenize\expandafter{\gitInf@firsttagdescribe}}
+\renewcommand{\gitReferences}{\detokenize\expandafter{\gitInf@refnames}}
+\newcommand{\git@vtag}[1]{%
+ \def\do##1{%
+ \StrCut{##1}{tag: }\lcut\rcut%
+ \IfEq{\rcut}{}{%
+ \IfDecimal{\lcut}{% case where we have decimal e.g. 1.0
+ \renewcommand{\gitVtag}{\lcut}
+ \renewcommand{\gitVtags}{\space\lcut}
+ \renewcommand{\gitVtagn}{\space\lcut}
+ \listbreak
+ }{}%
+ }{%
+ \IfDecimal\rcut{% case where we have string: decimal e.g. tag: 1.0
+ \renewcommand{\gitVtag}{\rcut}
+ \renewcommand{\gitVtags}{\space\rcut}
+ \renewcommand{\gitVtagn}{\space\rcut}
+ \listbreak
+ }{}%
+ }%
+ }%
+ \expandafter\docsvlist\expandafter{#1}%
+ \StrDel{#1}{(}[\bcut]%
+ \StrDel{\bcut}{)}[\bcut]%
+ \IfSubStr{\bcut}{->}{% git version 2+?
+ \StrBetween{\bcut,}{HEAD -> }{,}[\bcut]% yes - no problem
+ }{%
+ \StrCount{\bcut}{, }[\xcut]%
+ \IfEq{\xcut}{0}{% detached head?
+ }{% no
+ \StrCut[\xcut]{\bcut}{, }{\lcut}{\bcut}% git vv < 2 - take last token
+ }% (not always accurate)
+ }
+ \IfEq{\bcut}{}{}{%
+ \IfEq{\bcut}{HEAD}{% detached head?
+ }{% no - we have the branch name
+ \renewcommand{\gitBranch}{\detokenize\expandafter{\bcut}}%
+ }%
+ }%
+}%
+\newcommand{\git@taglist}[1]{%
+ \def\do##1{%
+ \StrCut{##1}{tag: }\llcut\rrcut%
+ \IfEq{\rrcut}{}{%
+ \IfDecimal{\llcut}{% case where we have decimal e.g. 1.0
+ \StrGobbleLeft{\gitTags,\space\llcut}{0}[\gitTags]
+ }{}%
+ }{%
+ \StrGobbleLeft{\gitTags,\space\rrcut}{0}[\gitTags]
+ }%
+ }%
+ \expandafter\docsvlist\expandafter{#1}%
+ \StrGobbleLeft{\gitTags}{2}[\gitTags]
+}%
+\newcommand{\git@rtag}[1]{%
+ \IfEq{#1}{}{}{%
+ \StrRight{#1}{2}[\gitInf@dirtflag]
+ \StrDel{#1}{-*}[\gitInf@describe]
+ \IfEq{\gitInf@dirtflag}{-*}{\renewcommand{\gitDirty}{\gitInf@dirty}}{}
+ \StrGobbleRight{\gitInf@describe}{9}[\gitInf@describe]% Remove -g<hash>
+ \StrCount{\gitInf@describe}{-}[\gitInf@mcount]% Find last -
+ \StrCut[\gitInf@mcount]{\gitInf@describe}{-}{\gitInf@rel}{\gitInf@off}
+ \renewcommand{\gitRel}{\detokenize\expandafter{\gitInf@rel}}
+ \renewcommand{\gitRels}{\space\gitRel}
+ \renewcommand{\gitReln}{\space\gitRel}
+ \renewcommand{\gitRoff}{\gitInf@off}
+ \renewcommand{\gitDescribe}{#1}
+ }%
+}%
+\git@vtag{\gitInf@refnames}
+\git@taglist{\gitInf@refnames}
+\git@rtag{\gitInf@reltag}
+\newcommand{\git@tagmark}{}
+\IfEq{\gitTags}{}{%
+ \renewcommand{\gitTags}{\gitInf@notags}
+ \ifbool{gitInf@marknotags}{%
+ \renewcommand{\git@tagmark}{\\Head tags: \gitTags}
+ }{%
+ }
+}{%
+ \renewcommand{\git@tagmark}{\\Head tags: \gitTags}
+}
+\renewcommand{\gitMark}{%
+ Branch: \gitBranch\,@\,\gitAbbrevHash{}
+ \textbullet{}
+ Release:\gitReln{}
+ (\gitAuthorDate)\git@tagmark%
+ }
diff --git a/macros/latex/contrib/gitinfo2/gitinfo2.pdf b/macros/latex/contrib/gitinfo2/gitinfo2.pdf
new file mode 100644
index 0000000000..14e22b307b
--- /dev/null
+++ b/macros/latex/contrib/gitinfo2/gitinfo2.pdf
Binary files differ
diff --git a/macros/latex/contrib/gitinfo2/gitinfo2.sty b/macros/latex/contrib/gitinfo2/gitinfo2.sty
new file mode 100644
index 0000000000..29a94918ce
--- /dev/null
+++ b/macros/latex/contrib/gitinfo2/gitinfo2.sty
@@ -0,0 +1,218 @@
+% gitinfo2.sty
+% Copyright 2015 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:
+% gitinfo2.sty, gitexinfo.sty, gitinfo2.tex, gitinfo2.pdf,
+% gitinfo2test.tex, post-xxx-sample.txt,
+% and gitHeadLocal.gin
+% -----------------------------------------------------
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesPackage{gitinfo2}[2015/11/22 v2.0.7 git revision information]
+\RequirePackage{etoolbox}
+\RequirePackage{xstring}
+\RequirePackage{kvoptions}
+\RequirePackage{eso-pic}
+\SetupKeyvalOptions{family=gitinfo,prefix=gitInf@}
+\DeclareBoolOption{draft}
+\DeclareBoolOption{grumpy}
+\DeclareBoolOption{local}
+\DeclareBoolOption{pcount}
+\DeclareBoolOption{footinfo}
+\DeclareBoolOption{mark}
+\DeclareBoolOption{markifdraft}
+\DeclareBoolOption{markifdirty}
+\DeclareBoolOption{marknotags}
+\DeclareStringOption[(None)]{missing}
+\DeclareStringOption[(None)]{notags}
+\DeclareStringOption[(*)]{dirty}
+\DeclareStringOption[4]{maxdepth}
+\DeclareStringOption[1.5\baselineskip]{raisemark}
+\ProcessKeyvalOptions*
+\newcommand{\gitAbbrevHash}{\gitInf@missing}
+\newcommand{\gitHash}{\gitInf@missing}
+\newcommand{\gitAuthorName}{\gitInf@missing}
+\newcommand{\gitAuthorEmail}{\gitInf@missing}
+\newcommand{\gitAuthorDate}{\gitInf@missing}
+\newcommand{\gitAuthorIsoDate}{\gitInf@missing}
+\newcommand{\gitAuthorUnixDate}{\gitInf@missing}
+\newcommand{\gitCommitterName}{\gitInf@missing}
+\newcommand{\gitCommitterEmail}{\gitInf@missing}
+\newcommand{\gitCommitterDate}{\gitInf@missing}
+\newcommand{\gitCommitterIsoDate}{\gitInf@missing}
+\newcommand{\gitCommitterUnixDate}{\gitInf@missing}
+\newcommand{\gitTags}{}
+\newcommand{\gitFirstTagDescribe}{\gitInf@missing}
+\newcommand{\gitReferences}{\gitInf@missing}
+\newcommand{\gitBranch}{\gitInf@missing}
+\newcommand{\gitVtag}{}
+\newcommand{\gitVtags}{}
+\newcommand{\gitVtagn}{\space\gitInf@missing}
+\newcommand{\gitRel}{}
+\newcommand{\gitRels}{}
+\newcommand{\gitReln}{\space\gitInf@missing}
+\newcommand{\gitDirty}{}
+\newcommand{\gitRoff}{}
+\newcommand{\gitDescribe}{(None)}
+\newcommand{\gitMarkPref}{[git]}
+\@ifpackageloaded{xcolor}{%
+ \newcommand{\gitMarkFormat}{\color{gray}\small\sffamily}%
+}{%
+ \newcommand{\gitMarkFormat}{\small\sffamily}%
+}
+\newcommand{\gitMark}{}
+\newcommand{\gitWrapEmail}[1]{#1}
+% private values
+\newif\ifGI@is@a@repo@
+
+% private constants
+\providecommand{\GI@repo@prefix}{}
+\ifbool{gitInf@local}{%
+ \providecommand{\GI@githeadinfo@file}{gitHeadLocal.gin}
+ \def\gitInf@maxdepth{0}
+}{%
+ \providecommand{\GI@githeadinfo@file}{\GI@repo@prefix.git/gitHeadInfo.gin}
+}
+\newcommand{\gitInf@dirtflag}{}
+\newcommand{\gitInf@describe}{}
+\newcommand{\gitInf@mcount}{}
+\newcommand{\gitInf@rel}{}
+\newcommand{\gitInf@off}{}
+
+% \TeX{}nical tools
+
+\newcommand\GI@export@macro[1]{%
+ \edef\@tempa{\endgroup
+ \def\noexpand#1{#1}}%
+ \@tempa}
+
+% finding the .git directory
+
+\newcommand\GI@check@repo@prefix{%
+ \GI@is@a@repo@true
+ \IfFileExists{./\GI@githeadinfo@file}{%
+ \edef\GI@repo@prefix{./}%
+ }{%
+ \GI@set@repo@prefix}}
+
+\newcommand\GI@set@repo@prefix{%
+ \begingroup \count@\gitInf@maxdepth\relax
+ \GI@set@repo@prefix@}
+
+\newcommand\GI@set@repo@prefix@{%
+ \advance\count@\m@ne
+ \ifnum\count@<\z@
+ % \expandafter\GI@not@a@git@repo
+ \endgroup\relax
+ \else
+ \edef\GI@repo@prefix{../\GI@repo@prefix}%
+ \IfFileExists{\GI@githeadinfo@file}{%
+ \PackageInfo{gitinfo2}{%
+ gitinfo2 found : \GI@githeadinfo@file \MessageBreak
+ }%
+ \GI@export@macro\GI@githeadinfo@file
+ }{%
+ \expandafter\GI@set@repo@prefix@}%
+ \fi}
+
+\GI@check@repo@prefix
+\InputIfFileExists{\GI@githeadinfo@file}{}{%
+ \ifbool{gitInf@grumpy}{%
+ \PackageError{gitinfo2}{I can't find the file '\GI@githeadinfo@file'\MessageBreak
+ Please check the manual (gitinfo2.pdf) \MessageBreak
+ if you need more details}{}
+ }{%
+ \PackageWarningNoLine{gitinfo2}{I can't find the file '\GI@githeadinfo@file'.\MessageBreak
+ All git metadata has been set to '\gitInf@missing'}
+ }
+}
+% ---------------------------------------------------------------------
+% Memoir support
+% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+\@ifclassloaded{memoir}{%
+ \ifbool{gitInf@pcount}{
+ \newcommand{\@gitPage}{\thepage/\thelastpage}
+ \addtodef{\frontmatter}{\renewcommand{\@gitPage}{\thepage}}{}
+ \addtodef{\mainmatter}{}{\renewcommand{\@gitPage}{\thepage/\thelastpage}}
+ }{%
+ \newcommand{\@gitPage}{\thepage}
+ }
+ \newcommand{\@gitFootRev}{Release\gitRels: \gitAbbrevHash{} (\gitAuthorDate)}
+ \newcommand{\@gitrFootRev}{%
+ \tiny\textsf{\raggedleft \@gitFootRev}%
+ }%
+ \newcommand{\@gitlFootRev}{%
+ \tiny\textsf{\@gitFootRev}%
+ }%
+ \copypagestyle{giplain}{plain}
+ \copypagestyle{giruled}{ruled}
+ \copypagestyle{giheadings}{headings}
+ \makeevenfoot{giplain}{\@gitPage}{}{\@gitrFootRev}
+ \makeoddfoot{giplain}{\@gitlFootRev}{}{\@gitPage}
+ \makeevenfoot{giruled}{\@gitPage}{}{\@gitrFootRev}
+ \makeoddfoot{giruled}{\@gitlFootRev}{}{\@gitPage}
+ \makeevenfoot{giheadings}{\@gitPage}{}{\@gitrFootRev}
+ \makeoddfoot{giheadings}{\@gitlFootRev}{}{\@gitPage}
+ \makeevenhead{giheadings}{}{}{\slshape\leftmark}
+ \makeoddhead{giheadings}{\slshape\rightmark}{}{}
+}{}%
+% ---------------------------------------------------------------------
+% Watermarking
+% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+\ifbool{gitInf@markifdirty}{%
+ \IfEq{\gitDirty}{}{}{%
+ \booltrue{gitInf@mark}
+ \renewcommand{\gitMarkPref}{[Dirty]}
+ }%
+}{}%
+\ifbool{gitInf@markifdraft}{%
+ \ifbool{gitInf@draft}{%
+ \booltrue{gitInf@mark}
+ \renewcommand{\gitMarkPref}{[Draft]}
+ }{}%
+}{}%
+\ifbool{gitInf@mark}{%
+ \AddToShipoutPictureBG{%
+ \AtPageLowerLeft{%
+ \raisebox{\gitInf@raisemark}{%
+ \makebox[\paperwidth]{%
+ \begin{minipage}[b]{\paperwidth}%
+ \renewcommand{\baselinestretch}{1}%
+ \centering{\gitMarkFormat\gitMarkPref{} \textbullet{} \gitMark}%
+ \end{minipage}%
+ }%
+ }%
+ }%
+ }%
+}{}%
+% ---------------------------------------------------------------------
+% Datetime integration
+% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+\@ifpackageloaded{datetime2}{%
+ \IfEq{\gitAuthorDate}{\gitInf@missing}{%
+ \DTMsavedate{gitdate}{\THEDAY-\THEMONTH-\THEYEAR}
+ }{%
+ \StrCut{\gitAuthorDate}{-}{\gitInf@year}{\gitInf@md}
+ \StrCut{\gitInf@md}{-}{\gitInf@month}{\gitInf@day}
+ \DTMsavenoparsedate{gitdate}{\gitInf@year}{\gitInf@month}{\gitInf@day}{-1}
+ }
+}{}%
+\@ifpackageloaded{datetime}{%
+ \IfEq{\gitAuthorDate}{\gitInf@missing}{%
+ \newdate{gitdate}{\THEDAY}{\THEMONTH}{\THEYEAR}
+ }{%
+ \StrCut{\gitAuthorDate}{-}{\gitInf@year}{\gitInf@md}
+ \StrCut{\gitInf@md}{-}{\gitInf@month}{\gitInf@day}
+ \newdate{gitdate}{\gitInf@day}{\gitInf@month}{\gitInf@year}
+ }
+}{}%
diff --git a/macros/latex/contrib/gitinfo2/gitinfo2.tex b/macros/latex/contrib/gitinfo2/gitinfo2.tex
new file mode 100644
index 0000000000..5f5ee4c055
--- /dev/null
+++ b/macros/latex/contrib/gitinfo2/gitinfo2.tex
@@ -0,0 +1,992 @@
+% gitinfo2.tex
+% Copyright 2015 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:
+% gitinfo2.sty, gitexinfo.sty, gitinfo2.tex, gitinfo2.pdf,
+% gitinfotest.tex, post-xxx-sample.txt,
+% and gitHeadLocal.gin
+% -----------------------------------------------------
+\documentclass[a4paper,12pt,twoside,openany]{memoir}
+% =====================================================
+\usepackage[british]{babel}
+\selectlanguage{british}
+\usepackage[style=iso]{datetime2}
+\usepackage[local,pcount,grumpy,mark,markifdirty]{gitinfo2}
+\usepackage{tgpagella}
+\usepackage{tgadventor}
+\usepackage{fontspec}
+\setmainfont[Numbers={Proportional,OldStyle},Ligatures=TeX]{TeX Gyre Pagella}
+\setsansfont[Numbers={Proportional,OldStyle},Ligatures=TeX]{TeX Gyre Adventor}
+\setmonofont{Consolas}
+\usepackage{enumitem}
+\setlist[description]{%
+ format=\ttfamily\bfseries,
+ style=nextline,
+ leftmargin=5em,
+ itemsep=0.5\onelineskip}
+\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]
+\makepagenote
+\continuousnotenums
+\notepageref
+\foottopagenote
+\renewcommand*{\printpageinnotes}[1]{%
+ (p.\pageref{#1})\space}
+\renewcommand\printpageinnoteshyperref[1]{%
+ (p.\pageref*{#1})\space}
+\renewcommand*{\pagenotesubhead}[3]{%
+ \subsubsection*{#1: #3}}
+\tightlists
+\chapterstyle{bringhurst}
+\pagestyle{empty}
+\aliaspagestyle{chapter}{empty}
+\settocdepth{subsection}
+\setsecnumdepth{none}
+\newcommand{\bpara}[1]{\par\vspace{\beforeparaskip}\noindent\textbf{#1}\,}
+\newcommand{\rpara}[1]{\par\noindent\textbf{#1}\,}
+\newcommand{\dark}[1]{\texttt\textbf{{#1}}}
+\newcommand{\sfit}[1]{\textit{#1}}
+\newcommand{\git}{\sfit{git}}
+\newcommand*{\emailat}{@}
+\newcommand{\opname}{\sfit{gitinfo}}
+\newcommand{\tpname}{\sfit{gitinfo2}}
+\newcommand{\tpfname}{\textsf{gitinfo2.sty}}
+\newcommand{\ginname}{gitHeadInfo.gin}
+\newcommand{\locname}{\texttt{gitHeadLocal.gin}}
+\newcommand{\metaname}{\texttt{\ginname}}
+\newcommand{\metapath}{\texttt{.git/\ginname}}
+% -----------------------------------------------------
+\usepackage[%
+ bookmarksnumbered,
+ bookmarksopen,
+ linktocpage,
+ ]{hyperref}
+\hypersetup{
+ pdfauthor={Brent Longborough},
+ pdftitle={The gitinfo2 package: git metadata for LaTeX},
+ pdfkeywords={git;metadata;dvcs},
+}
+\begin{document}
+\frontmatter
+% -----------------------------------------------------
+\title{%
+ ~\\[2\baselineskip]
+ \Huge \tpfname\\[2ex]%
+ \Large A package for accessing metadata\\from the \git\ \textsc{dvcs}
+ }
+\author{Brent Longborough}
+\date{\DTMenglishmonthname{\DTMfetchmonth{gitdate}} \DTMfetchyear{gitdate}}
+\maketitle
+
+{\centering
+Release:\gitReln\ (\gitAbbrevHash)\\
+}
+% -----------------------------------------------------
+\thispagestyle{empty}
+\aliaspagestyle{chapter}{plain}
+\clearforchapter
+\tableofcontents*
+% -----------------------------------------------------
+\mainmatter
+\pagestyle{giruled}
+\aliaspagestyle{chapter}{giplain}
+\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\{\metapath\}}
+in the repository (module or submodule) root.
+
+Under some circumstances
+(for example, when shipping something to \textsc{Ctan}),
+a document will not be able to access the standard metadata.
+In such a case, an option is available to read the metadata
+from a \emph{manual} copy in the current directory,
+called \locname.
+
+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 `\titleref{ch:using}'
+on page \pageref*{ch:using}.
+Then, if you like what you see, come back to
+read `\titleref{ch:setup}' later.
+
+% - - - - - - - - - - - - - - - - - - - - - - - - - - -
+\clearpage
+\section{Why a new package?}
+
+The improvements to \opname\ version~2 mean that
+existing repositories would not work;
+so if I just dumped a new version of \opname\
+on to CTAN, anyone who updated \opname\
+would need to migrate all their active repositories
+before they could resume work.
+
+So in order to avoid the rebukes that would follow,
+I have changed the package name to \tpname,
+and the inner package name from \sfit{gitsetinfo}
+to \sfit{gitexinfo}.
+
+\opname\ is now informally deprecated,
+and the first reply to any bug reports or feature requests
+will be `try \tpname'.
+Of course, I will support \tpname\ itself
+to the best of my somewhat limited ability.
+
+For obvious reasons, \emph{do not try}
+to use both packages in the same repository;
+for a new repository, use \tpname,
+and for an old one, either leave it alone with \opname,
+or migrate it to \tpname.
+
+To the administrators of CTAN,
+I'm sorry I caused you this clutter
+by not getting it right the first time.
+
+% -----------------------------------------------------
+\chapter{Setup and tailoring}
+\label{ch: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.
+
+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}
+(which is in the same folder of your \TeX{} distribution as this pdf)
+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 If you're using a unix-like system,
+don't forget to make the file executable.
+Just how you do this is outside the scope of this manual,
+but one possible way is with commands such as this:
+
+\begin{verbatim}
+chmod g+x post-checkout.
+\end{verbatim}
+
+\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.
+As before, users of unix-like systems should ensure these files are marked as executable.
+\end{enumerate}
+
+If you don't want to install \tpname\ using a package manager,
+you can instead just copy the two *.sty files into your document directory.
+However, it may be simpler, for more complex project trees,
+to install the package as part of your \TeX\ distribution.
+
+% - - - - - - - - - - - - - - - - - - - - - - - - - - -
+\section{Migrating from version 1}
+
+Version~2 of \tpname\ simplifies setup and brings additional convenience.
+But this comes at a cost:
+existing repositories need to be upgraded to be compatible.
+This decision wasn't taken lightly; I really do think the incompatible changes
+will give us a much firmer base for the future.
+The changes needed, which should be applied to every repository, follow.
+
+\bpara{Update \git\ hooks.}
+Replace the hooks (\texttt{post-checkout}, \texttt{post-commit},
+and \texttt{post-merge}) with the contents of the file \texttt{post-xxx-sample.txt}.
+Since \tpname\ now uses only a single \metaname\ file for the whole repository,
+you do \emph{not} need to tailor these hooks to map your document folders.
+
+If you are fortunate enough to be using a unix-like system,
+don't forget to ensure the hooks are executable.
+
+\bpara{Recreate the new \metaname\ file.}
+After you've replaced the hooks, the simplest way is to re-check-out the current branch,
+using a command such as \verb!git checkout!.
+
+\bpara{Delete the old \metaname\ files,}
+when you're ready.
+
+\bpara{If you're a \sfit{memoir} user,}
+and you use the \texttt{footinfo} package option,
+you will need to adjust your page styles.
+
+From \tpname\ version~2, we no longer override the standard \sfit{memoir}
+page styles.
+Instead, \tpname\ provides three new page styles:
+\sfit{giplain}, \sfit{giruled}, and \sfit{giheadings},
+which you should now use to provide \tpname-tailored pages.
+
+% - - - - - - - - - - - - - - - - - - - - - - - - - - -
+\section{Tailoring release tags}
+
+As shipped, the \git\ hook code uses a certain convention
+for identifying `release' tags:
+the tag must begin with a numeric digit, and contain at least one decimal
+point.\footnote{I.e. full stop or period, depending on which variant of English you use.}
+
+Here is the line in the hook where this convention is established:
+
+\begin{quotation}
+{\ttfamily
+RELTAG=\$(git describe \textellipsis\ --match '[0-9]*.*' \textellipsis)
+}
+\end{quotation}
+
+By changing the \texttt{--match} parameter, you can decide exactly which tags
+qualify as `release' tags for your needs. Thus
+
+\begin{quotation}
+{\ttfamily
+RELTAG=\$(git describe \textellipsis\ --match 'R.*' \textellipsis)
+}
+\end{quotation}
+would allow you to find tags like `R.2.0.1' and `R.L.Stevenson',
+or
+
+\begin{quotation}
+{\ttfamily
+RELTAG=\$(git describe \textellipsis\ --match '*' \textellipsis)
+}
+\end{quotation}
+would allow you to find any tag whatsoever.
+
+You can change the hooks without needing to alter \tpname,
+since any tag found is used `as-is'.
+
+\emph{Important note:} The \texttt{--match} parameter is a unix glob,
+\emph{not} a regular expression. This has tripped up a number of users.
+
+% -----------------------------------------------------
+\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,
+by loading the \tpname\ package in the usual way:\\[0.5\baselineskip]
+\texttt{\textbackslash usepackage[$<options>$]\{gitinfo2\}}
+
+% - - - - - - - - - - - - - - - - - - - - - - - - - - -
+\section{Package options}
+
+The following options are available:
+
+\subsection{General options}
+
+\begin{description}
+
+\item[local]
+By default, \tpname\ normally reads \metapath\ (the metadata file).
+If, however, the document needs to be shipped outside of its own repository,
+this file will not be found.
+Under these circumstances, the {\ttfamily local} option may be used.
+This option causes \tpname\ to search
+instead for \locname\ in the current directory \emph{only.}
+Creating this file
+(normally by copying from \metapath) is your responsibility.
+
+\item[grumpy]
+In those cases where \tpname\ is unable to find the metadata file
+(\metapath{}, or \locname\ if the {\ttfamily\bfseries local} option is used),
+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.
+
+\item[\texttt{missing=\textit{text}, notags=\textit{text}, dirty=\textit{text}}]
+These three options allow you to tailor the default text used by \tpname\ when
+metadata is missing `(None)',
+the branch head has no tags `(None)',
+and the working copy has uncommitted changes `(*)'.
+For example:
+
+\begin{quote}
+{\ttfamily
+[missing=Help!,notags=\{No\,tags?\},dirty=Eww!]
+}
+\end{quote}
+If you have complex needs, as in the second example,
+don't forget to enclose your text in \{\}s.
+
+\item[\texttt{maxdepth=\textit{n}}]
+In order to locate \metapath\ in the repository root,
+\tpname\ starts in the directory containing the master document,
+and searches up the directory tree until it finds it.
+This search is limited to {\ttfamily\itshape n} levels --- 4 by default.
+If have to deal with documents
+deeper in your repository tree, you can extend this limit with, say,
+{\ttfamily maxdepth=8}.
+
+\end{description}
+\clearpage
+\subsection{Options for watermarking}
+
+These options allow you to place a watermark of \git\ metadata,
+at the bottom of the paper, conditionally or unconditionally
+
+\begin{description}
+
+\item[mark]
+This option causes \tpname\ to generate a watermark,
+centred at the bottom of each sheet,
+containing `useful' \git\ metadata.
+The watermark is always added.
+
+\item[markifdraft]
+This option is like {\ttfamily\bfseries mark,}
+but only activates the watermark if the document is being processed
+with the {\ttfamily\bfseries draft} option.
+
+\item[markifdirty]
+This option is like {\ttfamily\bfseries mark,}
+but only activates the watermark if the last commit or checkout left
+uncommitted changes in the repository.
+
+\item[marknotags]
+If \tpname\ can't find any tags in the \git\ references,
+it suppresses the second line of the watermark.
+If, however, you would like the second line always to appear,
+add this option to the package options.
+
+\item[raisemark=\textit{vertical space}]
+By default, \tpname\ sets the bottom line of the watermark
+at 1.5 baseline
+skips\footnote{\texttt{1.5\textbackslash{}baselineskip},
+an admittedly arbitrary value, chosen for my Canon printer.}
+above the bottom of the paper.
+If you prefer something different,
+you can specify it here.
+For example:
+
+\begin{quote}
+{\ttfamily
+[raisemark=0.95\textbackslash{}paperheight]
+}
+\end{quote}
+
+
+\item[draft]
+This option \emph{should not be used;} it only exists to `capture' the
+{\ttfamily\bfseries draft} option from the document class definition.
+
+\end{description}
+
+\subsection{Options for \sfit{memoir} users}
+
+For more about these options,
+please read
+%The use of these options is described in more detail in
+`\titleref{sect:memuser}'
+on page~\pageref*{sect:memuser}.
+
+\begin{description}
+
+\item[footinfo]
+This option is no longer used, and if present is silently ignored.
+For \sfit{memoir} users, \tpname\ now creates, automatically,
+three new page styles.
+
+\item[pcount]
+For \sfit{memoir} users, this option will replace the folio
+in the new page styles 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.
+
+\end{description}
+% - - - - - - - - - - - - - - - - - - - - - - - - - - -
+\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:
+
+\begin{description}
+
+\item[gitReferences]
+ A list of any \git\ references (tags, branches) associated
+ with this commit.
+ This string is not for the faint-hearted;
+ its format and order may vary between versions of \git.\\
+ Example:\\\textit{\small\gitReferences}
+
+\item[gitBranch]
+ The name of the current branch.
+ Depending on how you use \git,\footnote{For example, checking out unnamed branches}
+ this information may not be available,
+ and will then be shown as the default or specified value of
+ the \texttt{missing} package option.
+ For \git{} versions before 2.0.0, where the current HEAD commit refers
+ to more than one branch head, this value may be different from the
+ currectly checked-out branch.\\
+ Example: \textit{\gitBranch}
+
+\item[gitDirty]
+ If the last commit or checkout left uncommitted changes in the working tree,
+ the default or specified value of the \texttt{dirty} package option;
+ otherwise empty.
+
+\item[gitAbbrevHash]
+ The seven-hex-char abbreviated commit hash\\
+ Example: \textit{\gitAbbrevHash}
+
+\item[gitHash]
+ The full 40-hex-character commit hash\\
+ Example: \textit{\gitHash}
+
+\item[gitAuthorName]
+ The name of the author of this commit\\
+ Example: \textit{\gitAuthorName}
+
+\item[gitAuthorEmail]
+ The email address of the author of this commit\\
+ Example: \textit{myemail\emailat evilspam.net}
+
+\item[gitAuthorDate]
+ The date this change was committed by the author,
+ in the format \textit{yyyy-mm-dd}\\
+ Example: \textit{\gitAuthorDate}
+
+\item[gitAuthorIsoDate]
+ The date and time this change was committed by the author,
+ in ISO format\\
+ Example: \textit{\gitAuthorIsoDate}
+\clearpage
+\item[gitAuthorUnixDate]
+ The date and time this change was committed by the author,
+ as a Unix timestamp\\
+ Example: \textit{\gitAuthorUnixDate}
+
+\item[gitCommitterName]
+ The name of the committer of this commit\\
+ Example: \textit{\gitCommitterName}
+
+\item[gitCommitterEmail]
+ The email address of the committer of this commit\\
+ Example: \textit{watcher\emailat gchq.gov.uk}
+
+\item[gitCommitterDate]
+ The date this change was committed by the committer,
+ in the format \textit{yyyy-mm-dd}\\
+ Example: \textit{\gitCommitterDate}
+
+\item[gitCommitterIsoDate]
+ The date and time this change was committed by the committer,
+ in ISO format\\
+ Example: \textit{\gitCommitterIsoDate}
+
+\item[gitCommitterUnixDate]
+ The date and time this change was committed by the committer,
+ as a Unix timestamp\\
+ Example: \textit{\gitCommitterUnixDate}
+
+\end{description}
+
+
+\subsection{Additional metadata (Version 1)}
+
+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:
+
+\begin{description}
+\item[gitVtag]
+ The version number, without decorations. If no version number is found,
+ empty (i.e. zero width).
+\item[gitVtags]
+ The version number, with a leading space. If no version number is found,
+ empty.
+\item[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.\\
+ Example: \textit{\gitVtagn}
+\end{description}
+
+These versioning tags have been superseded by release tags in Version 2,
+although they should continue to work as before.
+
+\subsection{Additional metadata (Version 2)}
+
+From Version 2 onwards, additional \git\ metadata is available,
+in general improving or extending the facilities available in Version 1.
+The Version 1 metadata is retained for backward compatibility.
+
+Included is a new set of \texttt{gitRel} commands,
+designed to replace \texttt{gitVtag} and its cousins.
+\tpname\ searches the \git\ metadata for tags
+on the current \textsc{head} commit or its ancestors,
+and makes the first tag found available.
+It also looks for the latest such tag
+whose name begins with a digit, and which contains a full stop (period),
+and makes the tag, and the number of commits following it,
+available as a `release number'.%
+\footnote{\tpname\ doesn't check for numerics, so you can use a tag like `1.5-beta' if you wish.}
+Here are the new commands in Version~2:
+
+\begin{description}
+
+\item[gitFirstTagDescribe]
+ The last tag reachable from the current \textsc{head}.
+ Please see git-describe for more information.
+ If the working copy is \textit{dirty} (has uncommitted changes),
+ the string has '-*' appended.\\
+ Example: \textit{\gitFirstTagDescribe}
+
+\item[gitRel]
+ The release number, without any decorations.
+ If no release number is found, empty (i.e. zero width).
+
+\item[gitRels]
+ The release number, with a leading space.
+ If no release number is found, empty.
+
+\item[gitReln]
+ The release number, with a leading space.
+ If no release number is found, a space,
+ followed by the default or specified value of
+ the \texttt{missing} package option.
+
+\item[gitRoff]
+ The number of commits between the current \textsc{head}
+ and the tag holding the release number.
+ If the tag refers to the current \textsc{head}, zero.
+
+\item[gitTags]
+ A comma-separated list of tags associated with the current \textsc{head}.\\
+ Example: \textit{\gitTags}
+
+\item[gitDescribe]
+ The raw output from the git-describe command for the last release tag
+ reachable from the current \textsc{head}, including tag name, commit offset,
+ short hash, and a dirty flag.
+ Please see git-describe for more information.
+ Example: \textit{\gitDescribe}
+
+\end{description}
+
+\clearpage
+\subsection{Watermark tailoring commands}
+
+If you use the Version 2 options to place a watermark,
+you can tailor the format of the watermark to suit your needs,
+by redefining one or more of the following commands.
+
+\begin{description}
+
+\item[gitMark]
+ Contains the text of the watermark.
+ Output from the default definition can be seen
+ below the footer
+ at the bottom of this page.
+ The definition
+ (here split onto four lines to fit)
+ is:
+
+\begin{verbatim}
+Branch: \gitBranch\,@\,\gitAbbrevHash{}
+\textbullet{}
+Release:\gitReln{} (\gitAuthorDate)\\
+Head tags: \gitTags
+\end{verbatim}
+You can tailor this by redefining \verb!\gitMark!.
+For example:
+
+\begin{verbatim}
+\renewcommand{\gitMark}{\gitHash\hfill\gitRel}
+\end{verbatim}
+
+\item[gitMarkFormat]
+ Defines typesetting parameters for the whole watermark.
+ The default definition is:
+
+\begin{verbatim}
+\color{gray}\small\sffamily
+\end{verbatim}
+if the \sfit{xcolor} package is loaded; if not, \verb!! is simply omitted.
+You can tailor this by redefining \verb!\gitMarkFormat!. For example:
+
+\begin{verbatim}
+\renewcommand{\gitMarkFormat}{\color(red)\ttfamily}
+\end{verbatim}
+
+\item[gitMarkPref]
+ Contains the text of the watermark prefix,
+ which depends on the reason the document is being watermarked.
+ The default values are \sfit{[Dirty]}, \sfit{[Draft]}, or \sfit{[git]}.
+ You can tailor this by redefining \verb!\gitMarkPref!. For example:
+
+\begin{verbatim}
+\renewcommand{\gitMarkPref}{[Pending review]}
+\end{verbatim}
+
+\end{description}
+
+% - - - - - - - - - - - - - - - - - - - - - - - - - - -
+\clearpage
+\section{Handling \TeX-hostile e-mail addresses}
+\label{sect:emailuser}
+Occasionally, a repository will contain `\TeX-hostile'
+e-mail addresses such as \verb!my_name@somewhere.net!.
+As a result, using the \dark{gitAuthorEmail}
+or \dark{gitCommitterEmail} commands can cause errors.
+
+\tpname\ provides an e-mail wrapping command,
+\verb!\gitWrapEmail!, to allow you to tailor your use
+of email addresses. Its default definition does nothing:
+\begin{verbatim}
+\newcommand{\gitWrapEmail}[1]{#1}
+\end{verbatim}
+You can tailor this by redefining \verb!\gitWrapEmail!.
+For example, a number of packages
+(\sfit{hyperref} is one) provide a \verb!\url! command
+which provides the necessary protection.
+Using such a package (independently of \tpname),
+you can redefine the \tpname\ wrapper in this way:
+\begin{verbatim}
+\renewcommand{\gitWrapEmail}[1]{\url{#1}}
+\end{verbatim}
+
+Please note that from Release 2.0.6 this precaution is optional,
+since \tpname\ now detokenises Author and Committer names and email addresses,
+and all \git\ reference names.
+
+% - - - - - - - - - - - - - - - - - - - - - - - - - - -
+\section{For \sfit{memoir} users}
+\label{sect:memuser}
+If you use \sfit{memoir}, \tpname\ provides you with
+three new pagestyles, based on
+\sfit{plain}, \sfit{ruled}, and \sfit{headings}.
+The new pagestyles are called
+\sfit{giplain}, \sfit{giruled}, and \sfit{giheadings}.
+
+For the \sfit{giplain} and \sfit{giruled} 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{giheadings} 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 you use the \texttt{pcount} option, a solidus, and the page count,
+are appended to the folio.
+
+The revision stamp is generated by this fragment:
+
+\begin{verbatim}
+ Release\gitRels: \gitAbbrevHash{} (\gitAuthorDate)
+\end{verbatim}
+\noindent
+which is set at tiny in the sans-serif font.
+
+Note that, in contrast to version 1 of \tpname,
+version 2 no longer modifies the existing page styles.
+If you wish to use this facility,
+you must now select
+the appropriate \sfit{gi\textellipsis} page style
+explicitly.
+
+You can see an example in the footer of this page,
+above the \tpname\ watermark.
+
+% - - - - - - - - - - - - - - - - - - - - - - - - - - -
+\section{For \sfit{datetime2} users}
+\label{sect:dtuser}
+If you use Nicola Talbot's excellent \sfit{datetime2} package,
+\tpname\ copies the value of the tag {\ttfamily\bfseries gitAuthorDate}
+as a new date object named \sfit{gitdate},
+which you can then refer to with other \sfit{datetime2}
+functions.
+
+Please refer to the \sfit{datetime2} manual for
+further details,
+especially in the section entitled `Saving Dates'.
+
+If you use it, you must load \sfit{datetime2}
+before you load \tpname.
+
+The \sfit{datetime} package is also supported,
+though deprecated.
+
+% - - - - - - - - - - - - - - - - - - - - - - - - - - -
+\section{Notes on the sequence of events}
+\label{sect:seqeve}
+Users of \tpname\ (including me) are frequently surprised
+by what appear to be incorrect results in their output,%
+\footnote{Most frequent are `wrong tag' and `falsely flagged as dirty'}
+but are determined in fact by the precise sequence of operations
+on a working copy.
+
+As it's impossible to foresee every possible workflow,
+what follows is a sequence of steps of a simple workflow
+which will serve as an example to help users
+to understand what is happening, and to avoid it.
+
+The example repository manages two main files:
+\sfit{abc.tex} and its output file, \sfit{abc.pdf}.%
+\footnote{Although derived files are often excluded from version control,
+the .pdf file in this case might need to be archived ---
+think of versions of a proposal, for example.}
+Intuitively, the overall sequence of one update \& release cycle
+might be like this:
+
+\begin{enumerate}
+\item Edit \sfit{abc.tex}, (perhaps) commit intermediate changes,
+format the output into \sfit{abc.pdf}, and
+check and repeat until ready for release;
+\item \label{wf:tex} Commit the release version of \sfit{abc.tex};
+\item \label{wf:tag} Tag the release;
+\item \label{wf:git} (Missing step);
+\item \label{wf:pdf} Format the release version of \sfit{abc.pdf}; and
+\item Commit the release version of \sfit{abc.pdf}.
+\end{enumerate}
+
+\noindent For reasons that I hope will become obvious,
+that doesn't work.
+The \git\ metadata is extracted and stored at step (\ref{wf:tex}).
+At that point, the release tag doesn't yet exist,
+and the working copy is dirty,
+since \sfit{abc.pdf} has been regenerated, and has changed
+since the last recorded version.
+
+It's simple to fix; all we have to do is
+ensure the working copy is clean and regenerate
+the saved metadata (now with correct tag information).
+Here's the missing step, kept, perhaps, somewhere in a \sfit{makefile:}
+
+\begin{enumerate}
+\item[\ref{wf:git}.] \texttt{git checkout abc.pdf}
+\end{enumerate}
+
+\noindent This will revert the .pdf file to its repository version,
+and then regenerate the stored metadata,
+including the release tag.
+Step (\ref{wf:pdf}) will now produce output showing the release tag
+and a clean working copy.
+% -----------------------------------------------------
+\chapter{Etc}
+\section{Release notes}
+
+\rpara{R2.0.7: 2015-11-22 -- Allow metadata to be shipped}
+\begin{itemize}
+\item
+Allow metadata to be read
+from \texttt{\locname} in the current directory,
+rather than from \metapath,
+via the \texttt{local} package option.
+\end{itemize}
+
+\rpara{R2.0.6: 2015-11-14 -- Detokenise the metadata}
+\begin{itemize}
+\item Detokenise names, emails, branches, and tags.
+This means you should be able to use branch names like \verb!yes@top_dol$lar! without
+\TeX\ chewing you out.
+I'd welcome feedback on this,
+as I have an uneasy feeling there may be unintended consequences.
+\end{itemize}
+
+\rpara{R2.0.5: 2015-11-09 -- Bug fixes and general improvements}
+\begin{itemize}
+\item Support for the \sfit{datetime2} package
+\item Provide correct committer metadata in hook sample
+\item Change Warning to Info when \sfit{gitHeadinfo.gin} is found
+\item Move all package dependencies from \sfit{gitexinfo.sty} to \sfit{gitinfo2.sty}
+\item Support for \git{} Version 2 log output, with more accurate branch name analysis
+\item Only use colours if the \sfit{xcolor} package is loaded
+\end{itemize}
+
+\rpara{R2.0.4: 2014-10-03 -- Fixes and documentation improvements}
+\begin{itemize}
+\item More robust \git\ hooks,
+for improved detection of dirty working copies
+\item A new section, \textit{\titleref{sect:seqeve}},
+to help with doing things in the right order
+\item Other minor improvements to the manual
+\end{itemize}
+
+\rpara{R2.0.3: 2014-09-05 -- Handle hostile e-mail addresses}
+\begin{itemize}
+\item Provide an e-mail address wrapper command,
+to allow users to tailor protection
+against `\_' and other characters in email addresses.
+\item This release was not shipped to \textsc{Ctan}
+\end{itemize}
+
+\rpara{R2.0.2: 2014-09-04 -- Mostly cosmetic}
+\begin{itemize}
+\item Fix packaging problems for \textsc{Ctan} and \TeX{}~Live
+\item Improve appearance of watermark
+\item Improve documentation: correct file references. remove gibberish, extend acknowledgments
+\end{itemize}
+
+\clearpage
+\section{Acknowledgements}
+
+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'd also like to register my thanks to the owners of the packages on which
+\tpname\ depends: datetime2, eso-pic, etoolbox, kvoptions, and xstring.
+
+Many people have written to me kindly
+to point out some of the defects in \opname, and to offer code.
+I owe you all an apology for the amount of time that elapsed
+from your suggestions to the making of \tpname.
+
+In some cases, I have not taken up suggestions other than as food for thought,
+in others used the code or suggestions directly, and,
+in yet others, adapted.
+I thank you all, especially for stimulating my thought processes,
+and thus, hopefully,
+helping to make \tpname\ a whole lot better than \opname.
+
+I think I owe a special mention, both for ideas and code,
+to Clea Rees, Jörg Weber, and Kai Mindermann
+for improving the handling of \git\ references;
+to Jörg Weber for watermarking;
+to Michael Rans and Ross Vandegrift for
+the deduplication of \metaname;
+and to \sfit{ivokabadshow} on GitHub
+for a welcome example of how to detokenise the metadata.
+
+My sincere thanks, too, to
+Adrian Burd,
+cedb12 (GitHub),
+Maximilian Held,
+Johannes Hoetzer,
+Mikko Korpela,
+Martin W Leidig,
+Enrico Malizia,
+Ken Mankoff,
+Ryan Matlock,
+Robbie Morrison,
+Nik (gwdg nokta de),
+Omid (gmail nokta com),
+Sasaki~Suguru,
+Tor\-bjørn~T (GitHub and TeX.SE),
+and
+Felix Wenger.
+
+Special thanks to Karl Berry for helping me to
+reduce my incompetence with \texttt{ctanify}.
+And, of course, for \TeX{} Live and everything else.
+
+Finally, but by no means least,
+my thanks to the \textsc{Ctan} elves, and their dæmons,
+particularly, in my case,
+Ina Dau,
+Manfred Lotz,
+Petra Rübe-Pugliese,
+and
+Robin Fairbairns,
+for their infinite patience and unstinting
+dedication to the \TeX\ community.
+
+The failings, of course, I claim for myself.
+
+% - - - - - - - - - - - - - - - - - - - - - - - - - - -
+\clearpage
+\section{Copyright \& licence}
+Copyright \copyright\ \DTMfetchyear{gitdate}, Brent Longborough,
+who has asserted his moral right
+to be identified as the author of this work.
+
+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 can be found
+at the \LaTeX\ Project website,%
+\footnote{(\url{http://www.latex-project.org/lppl.txt})}
+and version 1.3 or later is part of all recent distributions of
+\LaTeX.
+
+This work has the LPPL maintenance status `maintained';
+the Current Maintainer of this work is Brent Longborough.
+
+This work consists of the files
+gitinfo2.sty, gitexinfo.sty, gitinfo2.tex, gitinfo2.pdf,
+gitinfotest.tex, post-xxx-sample.txt,
+and gitHeadLocal.gin.
+
+% - - - - - - - - - - - - - - - - - - - - - - - - - - -
+\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+ctancontrib (bei) longborough (punkt) org}\\
+and at \href{http://tex.stackexchange.com/users/344/brent-longborough}{\TeX.SE}
+% -----------------------------------------------------
+\clearpage
+\raggedright
+\printpagenotes
+\end{document}
diff --git a/macros/latex/contrib/gitinfo2/gitinfotest.tex b/macros/latex/contrib/gitinfo2/gitinfotest.tex
new file mode 100644
index 0000000000..9e5d817aba
--- /dev/null
+++ b/macros/latex/contrib/gitinfo2/gitinfotest.tex
@@ -0,0 +1,38 @@
+\documentclass[10pt,a4paper,article,showtrims]{memoir}
+% =====================================================
+\usepackage[local,missing={(Oh my!)},dirty={Oh no!},markifdirty,marknotags]{gitinfo2}
+\frenchspacing
+\begin{document}
+
+\ttfamily
+!\gitMark! Mark
+
+!\gitReferences ! References
+
+!\gitVtag ! Vtag
+
+!\gitVtags ! Vtags
+
+!\gitVtagn ! Vtagn
+
+!\gitRel ! Rel
+
+!\gitRels ! Rels
+
+!\gitReln ! Reln
+
+!\gitFirstTagDescribe ! F.T.Describe
+
+!\gitDescribe ! Describe
+
+!\gitTags ! Tags
+
+!\gitDirty ! Dirty
+
+!\gitBranch ! Branch
+
+!\gitRoff ! Roff
+
+!\gitCommitterEmail! C.Email
+
+\end{document}
diff --git a/macros/latex/contrib/gitinfo2/post-xxx-sample.txt b/macros/latex/contrib/gitinfo2/post-xxx-sample.txt
new file mode 100644
index 0000000000..d9e6ddb89f
--- /dev/null
+++ b/macros/latex/contrib/gitinfo2/post-xxx-sample.txt
@@ -0,0 +1,31 @@
+#!/bin/sh
+# Copyright 2015 Brent Longborough
+# Part of gitinfo2 package Version 2
+# Release 2.0.7 2015-11-22
+# Please read gitinfo2.pdf for licencing and other details
+# -----------------------------------------------------
+# Post-{commit,checkout,merge} hook for the gitinfo2 package
+#
+# Get the first tag found in the history from the current HEAD
+FIRSTTAG=$(git describe --tags --always --dirty='-*' 2>/dev/null)
+# Get the first tag in history that looks like a Release
+RELTAG=$(git describe --tags --long --always --dirty='-*' --match '[0-9]*.*' 2>/dev/null)
+# Hoover up the metadata
+git --no-pager log -1 --date=short --decorate=short \
+ --pretty=format:"\usepackage[%
+ shash={%h},
+ lhash={%H},
+ authname={%an},
+ authemail={%ae},
+ authsdate={%ad},
+ authidate={%ai},
+ authudate={%at},
+ commname={%cn},
+ commemail={%ce},
+ commsdate={%cd},
+ commidate={%ci},
+ commudate={%ct},
+ refnames={%d},
+ firsttagdescribe={$FIRSTTAG},
+ reltag={$RELTAG}
+ ]{gitexinfo}" HEAD > .git/gitHeadInfo.gin