| 1 |
%% gitinfo-lua.tex |
| 2 |
%% Copyright 2023 E. Nijenhuis |
| 3 |
% |
| 4 |
% This work may be distributed and/or modified under the |
| 5 |
% conditions of the LaTeX Project Public License, either version 1.3c |
| 6 |
% of this license or (at your option) any later version. |
| 7 |
% The latest version of this license is in |
| 8 |
% http://www.latex-project.org/lppl.txt |
| 9 |
% and version 1.3c or later is part of all distributions of LaTeX |
| 10 |
% version 2005/12/01 or later. |
| 11 |
% |
| 12 |
% This work has the LPPL maintenance status ‘maintained’. |
| 13 |
% |
| 14 |
% The Current Maintainer of this work is E. Nijenhuis. |
| 15 |
% |
| 16 |
% This work consists of the files gitinfo-lua.sty gitinfo-lua.pdf |
| 17 |
% gitinfo-cmd.lua and gitinfo-lua.lua |
| 18 |
\documentclass{ltxdoc} |
| 19 |
\usepackage[english]{babel} |
| 20 |
\usepackage[titlepage,authors,rootdir]{gitinfo-lua} |
| 21 |
|
| 22 |
\usepackage{listings} |
| 23 |
\lstset{ |
| 24 |
columns=fullflexible, |
| 25 |
basicstyle=\ttfamily\lst@ifdisplaystyle\small\fi, |
| 26 |
commentstyle={\slshape}, |
| 27 |
showspaces=false, |
| 28 |
showstringspaces=false, |
| 29 |
breaklines=true, |
| 30 |
breakatwhitespace=true, |
| 31 |
breakindent=1em, |
| 32 |
prebreak=\raisebox{0ex}[0ex][0ex] |
| 33 |
{ \ensuremath{_{\kern-2.2pt\hookleftarrow}}} |
| 34 |
} |
| 35 |
\usepackage{calc} |
| 36 |
\usepackage{multicol} |
| 37 |
\usepackage{tabularx} |
| 38 |
\usepackage{xcolor} |
| 39 |
\usepackage{textcomp} |
| 40 |
|
| 41 |
\usepackage[orig,english]{isodate} |
| 42 |
|
| 43 |
\def\projecturl{https://github.com/Xerdi/gitinfo-lua} |
| 44 |
\title{\textbf{Gitinfo Lua} package\thanks{This document corresponds to package \texttt{gitinfo-lua} version \gitversion{} written on \gitdate{}.}} |
| 45 |
|
| 46 |
\def\cmd{\lstinline[language={[LaTeX]TeX},keywordsprefix={\\}]} |
| 47 |
|
| 48 |
\usepackage{hyperref} |
| 49 |
\usepackage[nonewpage]{imakeidx} |
| 50 |
|
| 51 |
\CodelineIndex |
| 52 |
\EnableCrossrefs |
| 53 |
|
| 54 |
\makeindex[columns=1] |
| 55 |
|
| 56 |
\newlength\xample |
| 57 |
\newlength\xamplesep |
| 58 |
\setlength\xample{6cm-5pt} |
| 59 |
\setlength\xamplesep{5pt} |
| 60 |
|
| 61 |
\begin{document} |
| 62 |
\RecordChanges |
| 63 |
|
| 64 |
\maketitle |
| 65 |
|
| 66 |
\begin{abstract} |
| 67 |
This project aims to display git project information in PDF documents. |
| 68 |
It's mostly written in Lua for executing the \texttt{git} commands, therefore making this package only applicable for \texttt{lualatex}. |
| 69 |
If \texttt{lualatex} isn't working for you, you could try \href{https://ctan.org/pkg/gitinfo2}{gitinfo2} instead. |
| 70 |
For \LaTeX{} it provides a set of standard macros for displaying basic information or setting the project directory, and a set of advanced macros for formatting commits and tags. |
| 71 |
\end{abstract} |
| 72 |
|
| 73 |
\begin{multicols}{2} |
| 74 |
\tableofcontents |
| 75 |
% \lstlistoflistings |
| 76 |
\printindex |
| 77 |
\end{multicols} |
| 78 |
\clearpage |
| 79 |
|
| 80 |
|
| 81 |
\section{Usage} |
| 82 |
For the package to work one should work, and only work, with Lua\TeX{}. |
| 83 |
Another prerequisite is that there is an available git repository either in the working directory, or somewhere else on your machine (see section~\ref{sub:tex-basic}). |
| 84 |
|
| 85 |
\subsection{Git} |
| 86 |
For this package to work at a minimum, there has to be an initialized Git repository, and preferably, at least with one commit. |
| 87 |
For example, the following minimal example should do the trick already: |
| 88 |
\begin{lstlisting}[language=bash,frame=single,caption={Minimal Git setup},morekeywords={mkdir,git}] |
| 89 |
mkdir my_project |
| 90 |
cd my_project |
| 91 |
echo "# My Project" > README.md |
| 92 |
git init && git commit -am "Init" |
| 93 |
\end{lstlisting} |
| 94 |
|
| 95 |
Then in order for the changelog to work, the project needs to contain either `lightweight-' or `annotated' tags. |
| 96 |
The main difference is that a lightweight tag takes no extra options, for example: \texttt{git tag 0.1}. |
| 97 |
See listing~\ref{lst:scenario} for more examples on authoring and versioning with \texttt{git}. |
| 98 |
|
| 99 |
\subsection{Lua\LaTeX{}} |
| 100 |
|
| 101 |
For generating the document with \LaTeX{} one must make use of \texttt{lualatex}. |
| 102 |
For example, when having the main file `\texttt{main.tex}': |
| 103 |
\begin{lstlisting}[language=bash,frame=single,caption={Generating the document with \LaTeX{}},morekeywords={lualatex,latexmk}] |
| 104 |
# Generate once |
| 105 |
lualatex -shell-escape main |
| 106 |
# Generate and keep watching with LaTeXMK |
| 107 |
latexmk -pvc -lualatex -shell-escape main |
| 108 |
\end{lstlisting} |
| 109 |
Note that in both cases option \texttt{--shell-escape} is required. |
| 110 |
This is required for issuing \texttt{git} via the commandline. |
| 111 |
If using \texttt{--shell-restricted} mode, which is the default, make sure to add \texttt{git} to the CSV variable \texttt{shell\_escape\_commands} in either your \texttt{texmf.cnf} or using a Lua initialization script, like: |
| 112 |
\lstinputlisting[language={[5.3]Lua},caption={Lua initialization script},frame=single]{gitinfo-lua-init.lua} |
| 113 |
|
| 114 |
\noindent |
| 115 |
The Lua initialization script can be used as follows: |
| 116 |
\begin{lstlisting}[language=bash,frame=single,caption={With Lua initialization script},morekeywords=lualatex] |
| 117 |
lualatex --lua=gitinfo-lua-init.lua main |
| 118 |
\end{lstlisting} |
| 119 |
For using the script with \texttt{latexmk}, this can be achieved with the \texttt{-lualatex="COMMAND"} option or specifying the \texttt{\$lualatex} command using a \texttt{latexmkrc} configuration file: |
| 120 |
\begin{lstlisting}[language=bash,frame=single,caption={Overriding Lua\LaTeX\ on commandline},morekeywords=latexmk] |
| 121 |
latexmk --lualatex --lualatex="lualatex --lua=gitinfo-lua-init.lua %O %S" main |
| 122 |
\end{lstlisting} |
| 123 |
\begin{lstlisting}[language=perl,frame=single,caption={Overriding Lua\LaTeX\ in \texttt{latexmkrc}}] |
| 124 |
$lualatex = "lualatex --lua=gitinfo-lua-init.lua %O %S"; |
| 125 |
\end{lstlisting} |
| 126 |
Keep in mind that both the Lua initialization script and \texttt{latexmkrc} need to be placed within the same directory as the main file.\\ |
| 127 |
|
| 128 |
When utilizing the continuous compilation option \texttt{-pvc} with \texttt{latexmk}, it's important to note that only committed changes will be detected, while tag changes, unfortunately, won't be recognized. |
| 129 |
|
| 130 |
\section{LaTeX Interface} |
| 131 |
|
| 132 |
\subsection{Package Options} |
| 133 |
|
| 134 |
\cmd{\usepackage}% |
| 135 |
\oarg{opts...}% |
| 136 |
\texttt{\textbraceleft gitinfo-lua\textbraceright}\index[pkgopts]{gitinfo-lua(.sty)} |
| 137 |
This package provides some options for default formatting purposes. |
| 138 |
The author sorting is one of them. |
| 139 |
If the options contain \texttt{contrib} the authors will be sorted based on their contributions; otherwise, the authors will be sorted alphabetically, which is the default option \texttt{alpha}. |
| 140 |
Another option is the \texttt{titlepage} option, which sets the \cmd{\author} and \cmd{\date} macros accordingly. |
| 141 |
By default, it sets the local git author, equivalent to option \texttt{author}. |
| 142 |
Pass the option \texttt{authors} to set all git authors of the project based on commit history instead. |
| 143 |
|
| 144 |
Another option, more concerning directory management, \texttt{rootdir}, sets the current working directory to the root directory of the current project for all \texttt{git} commands that are executed, similar to what \cmd{\gitdirectory} does. |
| 145 |
If you're using recording of files, this option comes in handy when the main file is in a subdirectory of the project. |
| 146 |
Otherwise, if the root directory isn't set appropriately, you'll receive the warning `\texttt{Warning: couldn't read HEAD from git project directory}'. |
| 147 |
|
| 148 |
\subsection{Basic macros}\label{sub:tex-basic} |
| 149 |
By default, the main file's directory is used as git project directory. |
| 150 |
This directory can be manipulated with \DescribeMacro{\gitdirectory}\cmd{\gitdirectory}\marg{path}. |
| 151 |
The foremost difference between using the \texttt{rootdir} option and the \cmd{gitdirectory} macro, is that the macro can specify a git directory which is part of another project. |
| 152 |
The main reason for this macro to exist is its usage in the project example in section~\ref{sec:project}. |
| 153 |
\DescribeMacro{\gitunsetdirectory} To undo an operation done with \cmd{\gitdirectory} and switch back to the main file's directory, use \cmd{\gitunsetdirectory}.\\ |
| 154 |
|
| 155 |
\DescribeMacro{\gitversion} The current version can be display by using \cmd{\gitversion} and is equivalent to \texttt{git describe --tags --always}, working for both lightweight and annotated tags. |
| 156 |
For this project \cmd{\gitversion} results in \gitversion. |
| 157 |
When the version is dirty it will be post fixed with \texttt{-<commit count>-<short ref>}. |
| 158 |
For example, when this paragraph was written, the version was displaying 0.0.1-14-gcc2bc30.\\ |
| 159 |
|
| 160 |
\DescribeMacro{\ifgitdirty} To test whether there are any pending changes in the local Git repository, use the \cmd{\ifgitdirty}\marg{true code}\marg{false code} macro. |
| 161 |
For this macro to work properly, be sure to add a \texttt{.gitignore}\footnote{A proper example of a \texttt{.gitignore} file for \LaTeX: \url{https://raw.githubusercontent.com/github/gitignore/main/TeX.gitignore}} file and include all \TeX\ based generated files.\\ |
| 162 |
|
| 163 |
The \DescribeMacro{\gitdate}\cmd{\gitdate} macro gets the most recent date from the git log. |
| 164 |
Meaning, the last `short date' variant is picked from the last commit. |
| 165 |
This short date is formatted ISO based and is already suitable for use in packages like \texttt{isodate} for more advanced date formatting.\\ |
| 166 |
|
| 167 |
|
| 168 |
The author's name and email can be accessed using \cmd{\gitauthor} and \cmd{\gitemail}\DescribeMacro{\gitauthor}\DescribeMacro{\gitemail}. |
| 169 |
These values are based on \texttt{git config user.name} and \texttt{git config user.email}. |
| 170 |
|
| 171 |
\subsection{Multiple Authors} |
| 172 |
When projects having multiple authors, this package can help with the \DescribeMacro{\dogitauthors}\cmd{\dogitauthors}\oarg{conj} and \DescribeMacro{\forgitauthors}\cmd{\forgitauthors}\oarg{conj}\marg{csname} macro. |
| 173 |
Where \cmd{\dogitauthors} executes a default formatting implementation of \cmd{\git@format@author} and \cmd{\forgitauthors} executes the given \meta{csname} for every author available. |
| 174 |
The optional \meta{conj} conjunction makes it possible to even integrate it further. |
| 175 |
For example, when setting the authors in pdfx, the conjunction would be \texttt{[\textbackslash\textbackslash sep ]}, so that the authors are properly separated in the document properties\footnote{See package documentation of \texttt{pdfx}: \url{https://ctan.org/pkg/pdfx}}. |
| 176 |
|
| 177 |
\gitdirectory{../../git-test-project}% |
| 178 |
\setlength\xample{4.6cm-5pt}% |
| 179 |
\setlength\xamplesep{5pt}% |
| 180 |
\noindent% |
| 181 |
\begin{minipage}[t]{\linewidth-\xample-\xamplesep}% |
| 182 |
\begin{lstlisting}[language={[LaTeX]TeX},numbers=left,caption={Formatting authors},captionpos=t,morekeywords={myauthorformat,href,forgitauthors,dogitauthors}] |
| 183 |
\newcommand{\myauthorformat}[2]{#1 \href{mailto:#2}{#2}} |
| 184 |
\forgitauthors[\\]{myauthorformat} |
| 185 |
% Or using standard format |
| 186 |
\dogitauthors[\\] |
| 187 |
\end{lstlisting} |
| 188 |
\end{minipage}\hfill% |
| 189 |
\begin{minipage}[t]{\xample} |
| 190 |
\noindent |
| 191 |
\begin{center} |
| 192 |
Results in |
| 193 |
\end{center} |
| 194 |
|
| 195 |
\noindent |
| 196 |
\setlength{\fboxsep}{5pt}% |
| 197 |
\fbox{\parbox{\linewidth-2\fboxsep}{\dogitauthors[\\\\]}} |
| 198 |
\end{minipage}\\ |
| 199 |
|
| 200 |
This example is generated with the history of the \texttt{git-test-project} (see section~\ref{sec:project}) and is alphabetically sorted with package option \texttt{alpha}. |
| 201 |
\gitunsetdirectory |
| 202 |
|
| 203 |
\subsection{Commits} |
| 204 |
For this section the git project of this document is used due to the fact that there are references to revisions. |
| 205 |
The test project's revisions change for every user, since they get recreated every time \texttt{test-scenario.sh} is executed (see section~\ref{sec:project}).\\ |
| 206 |
|
| 207 |
\noindent |
| 208 |
\DescribeMacro{\gitcommit}\oarg{format}\marg{csname}\marg{revision}\\ |
| 209 |
For displaying commit data \cmd{\gitcommit} can be used. |
| 210 |
The optional \texttt{format} takes variables separated by a comma. |
| 211 |
The default \texttt{format} is \texttt{h,an,ae,as,s,b}. |
| 212 |
The \texttt{csname} is a user defined command accepting every variable as argument.\\ |
| 213 |
\setlength\xample{3.5cm}% |
| 214 |
\setlength\xamplesep{0pt}% |
| 215 |
\noindent% |
| 216 |
\begin{minipage}[t]{\linewidth-\xample-\xamplesep} |
| 217 |
\begin{lstlisting}[language={[LaTeX]TeX},numbers=left,caption={Formatting a commit},captionpos=t,morekeywords={formatcommit,printdate,gitcommit}] |
| 218 |
\newcommand{\formatcommit}[3]{#1, by #2 on \printdate{#3}} |
| 219 |
|
| 220 |
\gitcommit[s,an,as]{formatcommit}{75dc036} |
| 221 |
\end{lstlisting} |
| 222 |
\end{minipage}\hfill% |
| 223 |
\begin{minipage}[t]{\xample} |
| 224 |
\noindent |
| 225 |
\begin{center} |
| 226 |
Results in |
| 227 |
\end{center} |
| 228 |
|
| 229 |
\noindent |
| 230 |
\setlength{\fboxsep}{5pt}% |
| 231 |
\newcommand\formatcommit[3]{#1, by #2 on \printdate{#3}}% |
| 232 |
\fbox{\parbox{\linewidth-2\fboxsep}{\gitcommit[s,an,as]{formatcommit}{75dc036}\footnotemark}} |
| 233 |
\end{minipage}\\ |
| 234 |
\footnotetext{\cs{printdate} from \texttt{isodate}: \url{https://www.ctan.org/pkg/isodate}} |
| 235 |
|
| 236 |
Consult \texttt{man git-log} for possible format variables and omit the \% for every variable.\\ |
| 237 |
|
| 238 |
\noindent |
| 239 |
\DescribeMacro{\forgitcommit}\oarg{format}\marg{csname}\marg{rev\_spec, files=\{...\}, flags=\{...\}, cwd=...}\\ |
| 240 |
For displaying multiple commits the~\cmd{\forgitcommit} is used, which has the same arguments as \cmd{\gitcommit}, but only this time the \texttt{csname} is executed for every commit. |
| 241 |
The last argument, which originally only took a \texttt{rev\_spec}, now also supports some additional `named' arguments. |
| 242 |
The argument \meta{files} takes a list of file names relative from the root of the git project. |
| 243 |
When \meta{files} is given, all commits will be filtered out accordingly. |
| 244 |
Currently, for \meta{flags}, only \texttt{merges} and \texttt{no-merges} are supported, which includes or excludes merge commits. |
| 245 |
The \meta{cwd} option is like \cmd{\gitdirectory}, but only for this call. |
| 246 |
|
| 247 |
\noindent\setlength\xample{4.5cm}\setlength\xamplesep{0pt} |
| 248 |
\begin{minipage}[t]{\linewidth-\xample-\xamplesep} |
| 249 |
\noindent |
| 250 |
\begin{lstlisting}[language={[LaTeX]TeX},numbers=left,captionpos=t,caption={Formatting commits},morekeywords={formatcommits,forgitcommit}] |
| 251 |
\newcommand{\formatcommits}[2]{\item #1\\\quad —#2} |
| 252 |
|
| 253 |
\begin{itemize} |
| 254 |
\forgitcommit[s,an]{formatcommits}{75dc036...e51c481} |
| 255 |
\end{itemize} |
| 256 |
\end{lstlisting} |
| 257 |
\end{minipage}\hfill% |
| 258 |
\begin{minipage}[t]{\xample} |
| 259 |
\noindent |
| 260 |
\begin{center} |
| 261 |
Results in |
| 262 |
\end{center} |
| 263 |
|
| 264 |
\noindent |
| 265 |
\newcommand\formatcommits[2]{\item #1\\\quad —#2}% |
| 266 |
\setlength{\fboxsep}{0pt}% |
| 267 |
\fbox{\parbox{\linewidth}{% |
| 268 |
\begin{itemize} |
| 269 |
\forgitcommit[s,an] |
| 270 |
{formatcommits} |
| 271 |
{75dc036...e51c481} |
| 272 |
\end{itemize} |
| 273 |
}} |
| 274 |
\end{minipage}\\ |
| 275 |
\gitdirectory{../../git-test-project} |
| 276 |
|
| 277 |
% \clearpage |
| 278 |
\subsection{Tags} |
| 279 |
In this section the \texttt{git-test-project} is used. |
| 280 |
|
| 281 |
The tags are mostly useful for generating changelogs. |
| 282 |
For formatting tags, there's a \DescribeMacro{\forgittag}\cmd{\forgittag}\oarg{format}\marg{csname}. |
| 283 |
Again, like \cmd{\forgitcommit} it takes a format, however, this time more complex, since the formatting options differ between \texttt{git log} and \texttt{git for-each-ref}. |
| 284 |
For more info regarding these formatting options consult the man page of \texttt{git-for-each-ref}. |
| 285 |
|
| 286 |
\noindent\setlength\xample{3.5cm}\setlength\xamplesep{0pt} |
| 287 |
\begin{minipage}[t]{\linewidth-\xample-\xamplesep} |
| 288 |
\noindent |
| 289 |
\begin{lstlisting}[language={[LaTeX]TeX},numbers=left,captionpos=t,caption={Formatting tags},morekeywords={formattags,forgittag}] |
| 290 |
\newcommand{\formattags}[2]{\item Version #1\\type: #2} |
| 291 |
|
| 292 |
\begin{itemize} |
| 293 |
\forgittag[refname:short,objecttype]{formattags} |
| 294 |
\end{itemize} |
| 295 |
\end{lstlisting} |
| 296 |
\end{minipage}\hfill% |
| 297 |
\begin{minipage}[t]{\xample} |
| 298 |
\noindent |
| 299 |
\begin{center} |
| 300 |
Results in |
| 301 |
\end{center} |
| 302 |
|
| 303 |
\noindent |
| 304 |
\newcommand\formattags[2]{\item Version #1\\type: #2}% |
| 305 |
\setlength{\fboxsep}{0pt}% |
| 306 |
\fbox{\parbox{\linewidth}{% |
| 307 |
\begin{itemize} |
| 308 |
\forgittag[refname:short,objecttype] |
| 309 |
{formattags} |
| 310 |
\end{itemize} |
| 311 |
}} |
| 312 |
\end{minipage}\\[1em] |
| 313 |
This example shows that the versions used are mixed. |
| 314 |
This is, of course, a horrible way to manage a project's version, though, we'll continue on with this hard objective. |
| 315 |
For example, if we wish to display the author of the lightweight and annotated tag, we can do so by specifying a format using the if-then-else feature of the format specification. |
| 316 |
The format would be: \texttt{(taggername)(taggername)(authorname)}. |
| 317 |
Here the \texttt{taggername} will show up, or if not present, the \texttt{authorname} will be shown instead. |
| 318 |
|
| 319 |
The default format specification is like the \cmd{\forgitcommit} format, but then again, some bit more complex:\\ |
| 320 |
|
| 321 |
\hfill\parbox{\linewidth-\parindent}{\texttt{refname:short,(taggername)(taggername,taggeremail,taggerdate:short)\\(authorname,authoremail,authordate:short),subject,body}}\\ |
| 322 |
|
| 323 |
\noindent |
| 324 |
This is a robust example of getting all information, being it either a lightweight- or annotated tag.\\ |
| 325 |
|
| 326 |
For displaying commits in between tags, there's a \DescribeMacro{\forgittagseq}\cmd{\forgittagseq}\marg{csname}. |
| 327 |
The \meta{csname} takes exactly three arguments, namely, the \meta{current}, \meta{next tag} and \meta{rev spec}. |
| 328 |
The last iteration gives an empty value for \meta{next tag} and the \meta{rev spec} is identical to \meta{current}.\\ |
| 329 |
|
| 330 |
Afterward tag info can be fetched using the \DescribeMacro{\gittag} \cmd{\gittag}\oarg{format}\marg{csname}\marg{tag}. |
| 331 |
This macro takes the same formatting specification as \cmd{\fotgittag}. |
| 332 |
Beware of using \cmd{\gittag} for the \meta{next tag} parameter in \cmd{\forgittagseq}. |
| 333 |
|
| 334 |
All these macros put together are demonstrated in listing~\ref{lst:changelog} (see next page). |
| 335 |
% \clearpage |
| 336 |
\subsection{Changelog} |
| 337 |
This example demonstrates the generation of a changelog. |
| 338 |
For simplicity’s sake, every tag is displayed in a \texttt{description} environment's item and within an \texttt{enumerate} environment displaying commits in between. |
| 339 |
\begin{lstlisting}[language={[LaTeX]TeX},numbers=left,captionpos=t,caption={Formatting a changelog},label={lst:changelog},morekeywords={commitline,formatversion,gittag,forgitcommit,forgittagseq,printdate}] |
| 340 |
\section*{Change History} |
| 341 |
\newcommand{\commitline}[1]{\item #1} |
| 342 |
\newcommand{\formatversion}[3]{% |
| 343 |
\item[#1] |
| 344 |
\gittag[(taggerdate)(taggerdate:short)(authordate:short)]{printdate}{#1} |
| 345 |
\begin{itemize} |
| 346 |
\forgitcommit[s]{commitline}{#3} |
| 347 |
\end{itemize} |
| 348 |
}% |
| 349 |
\begin{description} |
| 350 |
\forgittagseq{formatversion} |
| 351 |
\end{description} |
| 352 |
\end{lstlisting} |
| 353 |
\noindent |
| 354 |
\newcommand\commitline[2]{\item #1 |
| 355 |
|
| 356 |
#2} |
| 357 |
\newcommand\formatversion[3]{% |
| 358 |
\item[#1] \gittag[(taggerdate)(taggerdate:short)(authordate:short)]{printdate}{#1} |
| 359 |
\begin{itemize} |
| 360 |
\forgitcommit[s,b]{commitline}{#3} |
| 361 |
\end{itemize}% |
| 362 |
}% |
| 363 |
\setlength{\fboxsep}{16pt}% |
| 364 |
\begin{center}Results in\end{center} |
| 365 |
|
| 366 |
\noindent |
| 367 |
\fbox{ |
| 368 |
\parbox{\linewidth-8pt-2\fboxsep}{ |
| 369 |
{\bfseries\Large Change History} |
| 370 |
\begin{description} |
| 371 |
\forgittagseq{formatversion}% |
| 372 |
\end{description} |
| 373 |
} |
| 374 |
}\\[1em] |
| 375 |
|
| 376 |
\noindent |
| 377 |
For displaying the tagline (see line 5) we use the existing \cmd{\printdate} macro of package \texttt{isodate}, which also takes exactly one argument |
| 378 |
For every version sequence the commits in between are displayed (see line 7), where the last sequence having the initial commit as second argument plays well with the \cmd{\forgitcommit} macro and makes it possible to show the whole sequence of history. |
| 379 |
|
| 380 |
\section{Project Example}\label{sec:project} |
| 381 |
This documentation uses an example \texttt{project} which gets created by the \texttt{git-scenario.sh} script (see listing~\ref{lst:scenario}). |
| 382 |
It creates some commits having dates in the past and different authors set. |
| 383 |
Lastly it creates a `lightweight-' and `annotated' tag. |
| 384 |
|
| 385 |
To set up this scenario either do \texttt{make scenario} or execute \texttt{bash git-scenario.sh} in an initialized \texttt{git} repository. |
| 386 |
Keep in mind that when executing with Bash directly, you may need to specify the path to the Bash file. |
| 387 |
|
| 388 |
\lstinputlisting[language=bash,numbers=left,frame=single,label={lst:scenario},caption={git-scenario.sh},captionpos=t,morekeywords={git,alice,bob,charlie,mkdir,rm,curl,set\_author}]{git-scenario.sh} |
| 389 |
\end{document} |