summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2014-09-01 22:26:27 +0000
committerKarl Berry <karl@freefriends.org>2014-09-01 22:26:27 +0000
commit5e3775e74d3445586dfb14b025aa3b758c9fe50d (patch)
tree795198834b5daf95029d06e094baf7af3b3983fe /Master/texmf-dist/doc
parent90a719a4e36e91ce8d6c935f4ad9e5b1e50e2c49 (diff)
gitinfo2 (1sep14)
git-svn-id: svn://tug.org/texlive/trunk@35083 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc')
-rw-r--r--Master/texmf-dist/doc/latex/gitinfo2/README23
-rw-r--r--Master/texmf-dist/doc/latex/gitinfo2/gitPseudoHeadInfo.gin17
-rw-r--r--Master/texmf-dist/doc/latex/gitinfo2/gitinfo2.pdfbin0 -> 110855 bytes
-rw-r--r--Master/texmf-dist/doc/latex/gitinfo2/gitinfo2.tex801
-rw-r--r--Master/texmf-dist/doc/latex/gitinfo2/gitinfotest.tex48
5 files changed, 889 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/gitinfo2/README b/Master/texmf-dist/doc/latex/gitinfo2/README
new file mode 100644
index 00000000000..ee18c3b25d9
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/gitinfo2/README
@@ -0,0 +1,23 @@
+ 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
+~~~~~~~~~~~~~~
+
+Warning: existing repositories using gitinfo will need to be migrated
+in order to take advantage of the new features in gitinfo2.
+
+2014-05-12 2.0 Changed package name for backward compatibility
+ Improved documentation
+ New tags for improved Release annotation
+ A relocated 'gitHeadInfo.gin' file
+ Re-engineered page styles for Memoir users
+ Watermarking facility
+
+2011-08-29 1.0 Initial release
diff --git a/Master/texmf-dist/doc/latex/gitinfo2/gitPseudoHeadInfo.gin b/Master/texmf-dist/doc/latex/gitinfo2/gitPseudoHeadInfo.gin
new file mode 100644
index 00000000000..d1a7f3c5339
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/gitinfo2/gitPseudoHeadInfo.gin
@@ -0,0 +1,17 @@
+\usepackage[%
+ shash={3dfeae6},
+ lhash={3dfeae68bb3109a335704f4420958d4394329f15},
+ authname={Brent Longborough},
+ authemail={brent+ctancontrib@longborough.org},
+ authsdate={2014-05-17},
+ authidate={2014-05-17 17:08:57 +0100},
+ authudate={1400342937},
+ commname={Brent Longborough},
+ commemail={brent+ctancontrib@longborough.org},
+ commsdate={2014-05-17},
+ commidate={2014-05-17 17:08:57 +0100},
+ commudate={1400342937},
+ refnames={ (HEAD, develop)},
+ firsttagdescribe={2.0-13-g3dfeae6},
+ reltag={2.0-13-g3dfeae6}
+ ]{gitexinfo} \ No newline at end of file
diff --git a/Master/texmf-dist/doc/latex/gitinfo2/gitinfo2.pdf b/Master/texmf-dist/doc/latex/gitinfo2/gitinfo2.pdf
new file mode 100644
index 00000000000..30b7c3f396d
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/gitinfo2/gitinfo2.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/gitinfo2/gitinfo2.tex b/Master/texmf-dist/doc/latex/gitinfo2/gitinfo2.tex
new file mode 100644
index 00000000000..673e746d815
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/gitinfo2/gitinfo2.tex
@@ -0,0 +1,801 @@
+% gitinfo2.tex
+% Copyright 2014 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-git-sample.txt,
+% and gitPseudoHeadInfo.gin
+% -----------------------------------------------------
+\documentclass[a4paper,12pt,twoside,openany]{memoir}
+% =====================================================
+% This is a tweak to allow this document to be formatted
+% even when it doesn't live in an adequately configured
+% git repository. Please do not try this at home.
+% You have been warned.
+% -----------------------------------------------------
+\makeatletter
+\newcommand{\GI@repo@prefix}{}
+\newcommand{\GI@githeadinfo@file}{\GI@repo@prefix./gitPseudoHeadInfo.gin}
+\makeatother
+% -----------------------------------------------------
+% End of tweak
+% =====================================================
+\usepackage[nodayofweek]{datetime}
+\longdate{}
+\usepackage[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]
+\tightlists
+\chapterstyle{bringhurst}
+\pagestyle{empty}
+\aliaspagestyle{chapter}{empty}
+\settocdepth{section}
+\setsecnumdepth{none}
+\newcommand{\bpara}[1]{\par\vspace{\beforeparaskip}\noindent\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{\metaname}{\texttt{\ginname}}
+\newcommand{\metapath}{\texttt{.git/\ginname}}
+% -----------------------------------------------------
+\usepackage[%
+ bookmarksnumbered,
+ bookmarksopen,
+ linktocpage,
+ frenchlinks,
+ ]{hyperref}
+\hypersetup{
+ pdfauthor={Brent Longborough},
+ pdftitle={The gitinfo2 package: git metadata for LaTeX},
+ pdfkeywords={git;metadata;dvcs},
+}
+\begin{document}
+\frontmatter
+% -----------------------------------------------------
+\title{%
+ \Huge \tpfname\\[2ex]%
+ \Large A package for accessing metadata\\from the \git\ \textsc{dvcs}
+ }
+\author{Brent Longborough}
+\date{\displaydate{gitdate}}
+\maketitle
+
+{\centering
+Release:\gitReln\ (\gitAbbrevHash)\\
+}
+%\vspace*{2\baselineskip}
+% -----------------------------------------------------
+\begingroup
+\thispagestyle{empty}
+\aliaspagestyle{chapter}{empty}
+\setlength{\afterchapskip}{20pt}
+\let\clearpage\relax
+\let\chaptitlefont\Large\bfseries
+\vspace*{5\baselineskip}
+\tableofcontents*
+\endgroup
+% -----------------------------------------------------
+\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\{.git/\ginname\}}
+in the repository (module or submodule) root.
+
+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} 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 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 whatever tag is found is used as-is.
+
+% -----------------------------------------------------
+\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[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.
+
+\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=Yuck]
+}
+\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.\\
+ 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 three lines to fit)
+ is:
+
+\begin{verbatim}
+Branch: \gitBranch\,@\,\gitAbbrevHash{} /
+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}
+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.
+ is being printed.
+ 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{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{datetime} users}
+\label{sect:dtuser}
+If you use Nicola Talbot's excellent \sfit{datetime} package,
+\tpname\ creates a new date object named \sfit{gitdate},
+which you can then refer to with other \sfit{datetime}
+functions.
+
+Please refer to the \sfit{datetime} manual for
+further details,
+especially in the section entitled `Saving Dates'.
+
+If you use it, you must load \sfit{datetime}
+before you load \tpname.
+% -----------------------------------------------------
+\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: 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;
+and to Michael Rans and Ross Vandegrift for
+the deduplication of \metaname.
+
+My sincere thanks, too, to
+Adrian Burd,
+Felix Wenger,
+Johannes Hoetzer,
+Martin W Leidig,
+Nik (of gwdg nokta de),
+Omid (of gmail nokta com),
+Robbie Morrison,
+Ryan Matlock, and
+Sasaki~Suguru.
+
+Finally, but by no means least,
+my thanks to the \textsc{Ctan} elves, and their dæmons,
+particularly, in my case,
+Robin Fairbairns and Petra Rübe-Pugliese,
+for their infinite patience and unstinting
+dedication to the \TeX\ community.
+
+The failings, of course, I claim for my self.
+% - - - - - - - - - - - - - - - - - - - - - - - - - - -
+\section{Copyright \& licence}
+Copyright \copyright\ 2014, 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 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,
+post-git-sample.txt, and gitPseudoHeadInfo.gin.
+
+% - - - - - - - - - - - - - - - - - - - - - - - - - - -
+\clearpage
+\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}
+% -----------------------------------------------------
+\end{document}
diff --git a/Master/texmf-dist/doc/latex/gitinfo2/gitinfotest.tex b/Master/texmf-dist/doc/latex/gitinfo2/gitinfotest.tex
new file mode 100644
index 00000000000..4cc0bcbac3f
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/gitinfo2/gitinfotest.tex
@@ -0,0 +1,48 @@
+\documentclass[10pt,a4paper,article,showtrims]{memoir}
+% =====================================================
+% This is a tweak to allow this document to be formatted
+% even when it doesn't live in an adequately configured
+% git repository. Please do not try this at home.
+% You have been warned.
+% -----------------------------------------------------
+\makeatletter
+\newcommand{\GI@repo@prefix}{}
+\newcommand{\GI@githeadinfo@file}{\GI@repo@prefix./gitPseudoHeadInfo.gin}
+\makeatother
+% -----------------------------------------------------
+% End of tweak
+% =====================================================
+\usepackage[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
+
+\end{document}