From e0c6872cf40896c7be36b11dcc744620f10adf1d Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Mon, 2 Sep 2019 13:46:59 +0900 Subject: Initial commit --- macros/latex/contrib/gitinfo2/README | 15 + macros/latex/contrib/gitinfo2/gitHeadLocal.gin | 17 + macros/latex/contrib/gitinfo2/gitexinfo.sty | 138 +++ macros/latex/contrib/gitinfo2/gitinfo2.pdf | Bin 0 -> 127175 bytes macros/latex/contrib/gitinfo2/gitinfo2.sty | 218 +++++ macros/latex/contrib/gitinfo2/gitinfo2.tex | 992 ++++++++++++++++++++++ macros/latex/contrib/gitinfo2/gitinfotest.tex | 38 + macros/latex/contrib/gitinfo2/post-xxx-sample.txt | 31 + 8 files changed, 1449 insertions(+) create mode 100644 macros/latex/contrib/gitinfo2/README create mode 100644 macros/latex/contrib/gitinfo2/gitHeadLocal.gin create mode 100644 macros/latex/contrib/gitinfo2/gitexinfo.sty create mode 100644 macros/latex/contrib/gitinfo2/gitinfo2.pdf create mode 100644 macros/latex/contrib/gitinfo2/gitinfo2.sty create mode 100644 macros/latex/contrib/gitinfo2/gitinfo2.tex create mode 100644 macros/latex/contrib/gitinfo2/gitinfotest.tex create mode 100644 macros/latex/contrib/gitinfo2/post-xxx-sample.txt (limited to 'macros/latex/contrib/gitinfo2') 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 + \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 Binary files /dev/null and b/macros/latex/contrib/gitinfo2/gitinfo2.pdf 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[$$]\{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 -- cgit v1.2.3