Debian Codegraph @

texmf-dist/doc/lualatex/gitinfo-lua/gitinfo-lua.tex

raw
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}