Debian Codegraph @

texmf-dist/source/latex/latexgit/latexgit.dtx

raw
1 % \iffalse vim: expandtab:
2 % \fi
3 % \iffalse meta-comment
4 %<*internal>
5 \def\nameofplainTeX{plain}
6 \ifx\fmtname\nameofplainTex\else
7 \expandafter\begingroup
8 \fi
9 %</internal>
10 %<*install>
11 \input docstrip.tex
12 \keepsilent
13 \askforoverwritefalse
14 \preamble
15 latexgit
16 Author: Camil Staps <[email protected]>
17 \endpreamble
18 \postamble
19 Copyright (c) 2016-2020 Camil Staps <[email protected]>
20 Licensed under GPL v3.
21 \endpostamble
22 \usedir{tex/latex/latexgit}
23 \generate{
24 \file{\jobname.sty}{\from{\jobname.dtx}{package}}
25 }
26 %</install>
27 %<install>\endbatchfile
28 %<*internal>
29 \usedir{source/latex/latexgit}
30 \generate{
31 \file{\jobname.ins}{\from{\jobname.dtx}{install}}
32 }
33 \nopreamble\nopostamble
34 \ifx\fmtname\nameofplainTeX
35 \expandafter\endbatchfile
36 \else
37 \expandafter\endgroup
38 \fi
39 %</internal>
40 %<*driver>
41 \documentclass{ltxdoc}
42 \usepackage[T1]{fontenc}
43 \usepackage{lmodern}
44 \usepackage{\jobname}
45 \usepackage[numbered]{hypdoc}
46 \usepackage{showexpl}
47 \usepackage{xcolor}
48 \lstset{%
49 basicstyle=\ttfamily\small,
50 commentstyle=\itshape\ttfamily\small,
51 showspaces=false,
52 keepspaces=true,
53 showstringspaces=false,
54 breaklines=true,
55 backgroundcolor=\color{lightgray},
56 breakautoindent=true,
57 }
58 \usepackage{enumitem}
59 \usepackage{verbatim}
60 \usepackage{amssymb}
61 \usepackage{xstring}
62 \EnableCrossrefs
63 \CodelineIndex
64 \RecordChanges
65 \setcounter{IndexColumns}2
66 \newlist{options}{description}{1}
67 \setlist[options]{font=\small\texttt,itemsep=0pt,style=nextline}
68 \newcommand{\git}[0]{\gitcmd{git}}
69 \newcommand{\gitcmd}[1]{\texttt{\small#1}}
70 \newcommand{\gitopt}[1]{%
71 \texttt{\small\hyperref[options]{\textcolor{black}{#1}}}%
72 }
73 \newcommand{\bashcmd}[1]{\texttt{\small#1}}
74 \newcommand{\texcmd}[1]{\texttt{\small#1}}
75 \def\GitOptions#1,#2\relax{%
76 \gitopt{#1}%
77 \begingroup%
78 \ifx\relax#2\relax %
79 \def\next{\endgroup}%
80 \else%
81 \def\next{, \endgroup\GitOptions#2\relax}%
82 \fi%
83 \next%
84 }
85 \def\gitoptions#1{%
86 Recognised options:
87 \begingroup%
88 \edef\@tempa{#1,}%
89 \expandafter\endgroup%
90 \expandafter\GitOptions\@tempa\relax%
91 \unskip.
92 }
93 \begin{document}
94 \DocInput{\jobname.dtx}
95 \newpage
96 \PrintChanges
97 \newpage
98 \PrintIndex
99 \end{document}
100 %</driver>
101 % \fi
102 %
103 %\GetFileInfo{\jobname.sty}
104 %
105 %\title{The \latexgit{} package}
106 %\author{Camil Staps\thanks{Email: [email protected]}}
107 %\date{^^A
108 % Version \gitcommithash[shortHash]\\
109 % \small{\gitcommitdate[formatDate,formatTime,formatInterDateTime={,~},showTimeZone]}}
110 %
111 %\maketitle
112 %
113 %\gitchanges
114 %
115 %\DoNotIndex{\def,\edef,\expandafter,\global,\let,\newcommand,\relax,\catcode}
116 %\DoNotIndex{\%,\&} % this does not work currently due to a known bug
117 %\DoNotIndex{\begingroup,\endgroup}
118 %\expandafter\DoNotIndex\expandafter{\string\^}
119 %\DoNotIndex{\hbox,\ifdim,\setbox,\wd}
120 %\DoNotIndex{\ifeof,\else,\fi,\newif}
121 %\DoNotIndex{\NeedsTeXFormat,\PackageError,\ProvidesPackage,\RequirePackage}
122 %\DoNotIndex{\endlinechar,\newread,\openin,\read,\readline}
123 %\DoNotIndex{\space,\unskip}
124 %\DoNotIndex{\LaTeX,\pgfkeys,\changes}
125 %\DoNotIndex{\formatdate,\formattime}
126 %\DoNotIndex{\StrSubstitute}
127 %\DoNotIndex{\git@@revision,\git@@thisdate,\git@@thishash,\git@@thismsg,\git@@parent}
128 %
129 %\begin{abstract}
130 % This is the documentation of the \latexgit{} package.
131 % Several macros are defined to fetch \git{} information and typeset it.
132 % The macros defined by \latexgit{} can be helpful to documentation authors
133 % and others to whom clear document versioning is important.
134 %\end{abstract}
135 %
136 %\tableofcontents
137 %
138 %\section{Overview}
139 %\label{sec:overview}
140 %\subsection{Related packages}
141 %\label{sec:overview:related-packages}
142 %Brent Longborough's \textsf{gitinfo} and \textsf{gitinfo2} packages have
143 %similar features, with a different interface. Instead of running \git{}
144 %commands, it relies on special \git{} files. This has the advantage that it
145 %works on Windows, however, \git{} hooks have to be put into place.
146 %
147 %Andr\'e Hilbig's \textsf{gitfile-info} does something similar as
148 %\textsf{gitinfo} and \latexgit, but the package manual is in German so who
149 %knows. It seems that Python and \git{} hooks are required.
150 %
151 %\subsection{Dependencies}
152 %\label{sec:overview:dependencies}
153 %\latexgit{} gets its information by running \git{} commands. It uses
154 %\cs{write18} for this, so documents using \latexgit{} will have to be compiled
155 %with the \bashcmd{-shell-escape} flag.
156 %
157 %Most of the information is retrieved using \git{} but then parsed using
158 %\bashcmd{grep}, \bashcmd{cut} and similar tools. Unfortunately, this is
159 %necessary: \gitcmd{git log} accepts arbitrary formats, but uses the percent
160 %sign in these formats, and running commands with percent signs does not seem
161 %possible using \cs{write18}.
162 %
163 %An unfortunate side effect of this is that this package will not work on
164 %Windows.
165 %
166 %\subsection{Getting information}
167 %\label{sec:overview:getting-information}
168 %\latexgit{} runs a shell command using \cs{git@command}. This macro reads the
169 %result into \cs{git@rawresult.} This result contains a newline character at
170 %the end that needs to be removed to avoid unwanted spacing. Therefore,
171 %\cs{git@result} is defined as a wrapper for \cs{git@rawresult} that removes
172 %this spacing with \cs{unskip}.
173 %
174 %\subsection{Interface}
175 %For each information-fetching command, two versions are defined: one, which
176 %only executes the command (leaving the result available in \cs{git@result});
177 %and one, which executes the command and writes the result. An example is
178 %\cs{git@commithash} with its counterpart \cs{gitcommithash}. Usually, the
179 %latter is most useful.
180 %
181 %\section{Options}
182 %\label{sec:options}
183 %A number of options is available to all macros that fetch information through
184 %a \textsf{pgfkeys} interface. All keys are recognised by all macros, but not
185 %all are considered by each macro. Check the documentation for specific macros
186 %to see which options are relevant.
187 %
188 %\begin{options}
189 % \label{options}
190 % \item[directory=DIR]
191 % Use the git repository in directory \verb$DIR$ (or its first parent
192 % directory that is a git repository). \latexgit{} will \bashcmd{cd} to this
193 % directory before executing the actual \git{} command.
194 % \item[file=FILE]
195 % Get the information for the last commit modifying \verb$FILE$.
196 % \item[formatDate]
197 % Format dates using \textsf{datetime}'s \cs{formatdate}.
198 % \item[formatTime]
199 % Format times using \textsf{datetime}'s \cs{formattime}.
200 % \item[formatInterDateTime]
201 % If both \gitopt{formatDate} and \gitopt{formatTime} are set, this is put
202 % in between (e.g. `\verb$\space{}at\space{}$' in English --- this is also
203 % the default).
204 % \item[revision=REV]
205 % Get the hash of revision \verb$REV$ (e.g. \gitcmd{master},
206 % \gitcmd{HEAD\textasciicircum}, etc.). Note that if multiple circumflexes
207 % are desired, the catcode of \verb$^$ has to be changed. For example:
208 % \LTXinputExample[numbers=none,pos=r]{exmp/catcode-circumflex.tex}
209 % \item[showTimeZone]
210 % When \gitopt{formatTime} is set: show the time zone between parentheses
211 % after the time.
212 % \item[shortHash]
213 % Get only the first seven characters of the hash, as in \gitcmd{git log
214 % -{}-oneline}.
215 %\end{options}
216 %
217 %\section{Examples}
218 %\label{sec:examples}
219 %\DescribeMacro{\gitcommithash}
220 %\DescribeMacro{\gitcommitmsg}
221 %\DescribeMacro{\gitcommitauthor}
222 %\DescribeMacro{\gitcommitauthorname}
223 %\DescribeMacro{\gitcommitauthoremail}
224 % These macros are used to get and print basic commit information.
225 % \LTXinputExample[pos=b,numbers=none]{exmp/gitcommit.tex}
226 %
227 %\DescribeMacro{\gitcommitdate}
228 % This macro displays the \git{} commit date.
229 % The following example shows the effect of the options
230 % \gitopt{formatDate}, \gitopt{formatTime} and \gitopt{showTimeZone}.
231 % \LTXinputExample[pos=b,numbers=none]{exmp/gitcommitdate.tex}
232 %
233 %\DescribeMacro{\gitcommand}
234 % This macro executes an arbitrary \git{} command and directly typesets the
235 % result. It only accepts the option \gitopt{directory}.
236 % \LTXinputExample[pos=b,numbers=none]{exmp/gitcommand.tex}
237 %
238 %\section{Implementation}
239 %\label{sec:implementation}
240 %Define the package and load required packages.
241 %
242 % \begin{comment}
243 %<*package>
244 % \end{comment}
245 % \begin{macrocode}
246 \NeedsTeXFormat{LaTeX2e}
247 \ProvidesPackage{latexgit}[2020/04/20]
248
249 \RequirePackage{pgfkeys}
250 \RequirePackage{datetime}
251 % \end{macrocode}
252 %
253 %\begin{macro}{\latexgit}
254 % Prints the name of the package.
255 % \begin{macrocode}
256 \newcommand{\latexgit}[0]{\LaTeX{}git}
257 % \end{macrocode}
258 %\end{macro}
259 %
260 %\begin{macro}{\git@result}
261 % When a \git{} command is run, the result is stored in \cs{git@rawresult}.
262 % However, using \cs{read} results in spacing at the end of the macro.
263 % Hence, we need to use \cs{unskip} to remove this spacing.
264 % This is a wrapper for \cs{git@rawresult} that adds this \cs{unskip}.
265 % \begin{macrocode}
266 \newcommand{\git@result}[0]{\git@rawresult\unskip}
267 % \end{macrocode}
268 %\end{macro}
269 %
270 % We now define the keys accepted by git macros. The following options are
271 % recognised. Check the documentation of the macro to see which options are
272 % considered.
273 %
274 % \begin{macrocode}
275 \newif\ifgit@opt@FormatDate
276 \newif\ifgit@opt@FormatTime
277 \newif\ifgit@opt@ShortHash
278 \newif\ifgit@opt@ShowTimeZone
279 \pgfkeys{
280 /git/.is family, /git,
281 default/.style={
282 directory=.,
283 file=,
284 formatDate=false,
285 formatInterDateTime=\space{}at\space{},
286 formatTime=false,
287 revision=HEAD,
288 showTimeZone=false,
289 shortHash=true,
290 },
291 directory/.estore in=\git@opt@Directory,
292 file/.estore in=\git@opt@File,
293 formatDate/.is if=git@opt@FormatDate,
294 formatInterDateTime/.estore in=\git@opt@FormatInterDateTime,
295 formatTime/.is if=git@opt@FormatTime,
296 revision/.estore in=\git@opt@Revision,
297 showTimeZone/.is if=git@opt@ShowTimeZone,
298 shortHash/.is if=git@opt@ShortHash,
299 }
300 % \end{macrocode}
301 %
302 %\begin{macro}{\git@command}
303 % Run a \git{} command and read the output into \cs{git@rawresult}. Before
304 % running the command, the directory will change to \cs{git@opt@Directory}.
305 % \begin{macrocode}
306 \newread\git@stream%
307 \newcommand{\git@command}[1]{%
308 \def\git@rawresult{}%
309 \openin\git@stream|"cd \git@opt@Directory; #1"
310 \ifeof\git@stream%
311 \PackageError{latexgit}%
312 {invoke LaTeX with the -shell-escape flag}%
313 {invoke LaTeX with the -shell-escape flag}%
314 \else%
315 \begingroup%
316 \catcode`\^^M9%
317 \endlinechar=-1%
318 \readline\git@stream to \git@streamoutput%
319 \global\let\git@rawresult\git@streamoutput%
320 \endgroup%
321 \fi%
322 }
323 % \end{macrocode}
324 %\end{macro}
325 %
326 %\begin{macro}{\gitcommand}
327 % A wrapper around \cs{git@command} and \cs{git@result}, to directly typeset the
328 % result of arbitrary commands.
329 % \begin{macrocode}
330 \newcommand{\gitcommand}[2][]{%
331 \pgfkeys{/git,default,#1}%
332 \git@command{git #2}%
333 \git@result}
334 % \end{macrocode}
335 %\end{macro}
336 %
337 %In what follows, \verb$%$ may be used in calls to \git{}. Therefore we use
338 %\verb$&$ as comment character.
339 % \begin{macrocode}
340 \catcode`\&=14\catcode`\%=11
341 % \end{macrocode}
342 %
343 %\begin{macro}{\git@space}
344 % For internal use, when a space is required after a \texttt{csname} in a
345 % call to \cs{git@command}.
346 % \begin{macrocode}
347 \def\git@space{ }
348 % \end{macrocode}
349 %\end{macro}
350 %
351 %\begin{macro}{\gitcommithash}
352 % Get a commit hash.
353 % \gitoptions{directory,revision,shortHash}
354 %
355 % \begin{macrocode}
356 \newcommand{\gitcommithash}[1][]{&
357 \git@commithash[#1]\git@result}
358 % \end{macrocode}
359 %\end{macro}
360 %
361 %\begin{macro}{\git@commithash}
362 % Like \cs{gitcommithash}, but does not return the output.
363 % \begin{macrocode}
364 \newcommand{\git@commithash}[1][]{&
365 \pgfkeys{/git,default,#1}&
366 \ifgit@opt@ShortHash&
367 \git@command{git log -n 1 --format=%h
368 \git@opt@Revision\git@space -- \git@opt@File}&
369 \else&
370 \git@command{git log -n 1 --format=%H
371 \git@opt@Revision\git@space -- \git@opt@File}&
372 \fi&
373 }
374 % \end{macrocode}
375 %\end{macro}
376 %
377 %\begin{macro}{\gitcommitmsg}
378 % Get a commit message.
379 % \gitoptions{directory,revision}
380 %
381 % \begin{macrocode}
382 \newcommand{\gitcommitmsg}[1][]{&
383 \git@commitmsg[#1]\git@result}
384 % \end{macrocode}
385 %\end{macro}
386 %
387 %\begin{macro}{\git@commitmsg}
388 % Like \cs{gitcommitmsg}, but does not return the output.
389 % \begin{macrocode}
390 \newcommand{\git@commitmsg}[1][]{&
391 \pgfkeys{/git,default,#1}&
392 \git@command{git log -n 1 --format=%B
393 \git@opt@Revision\git@space -- \git@opt@File}&
394 }
395 % \end{macrocode}
396 %\end{macro}
397 %
398 %\begin{macro}{\git@formatCommitDate}
399 % Format a commit date in ISO format using \textsf{datetime}'s
400 % \cs{formatdate}.
401 % \begin{macrocode}
402 \def\git@formatCommitDate#1-#2-#3 #4:#5:#6 +#7\relax{&
403 \formatdate{#3}{#2}{#1}&
404 }
405 % \end{macrocode}
406 %\end{macro}
407 %
408 %\begin{macro}{\git@formatCommitTime}
409 % Format a commit time using \textsf{datetime}'s \cs{formattime}.
410 % \gitoptions{showTimeZone}
411 % \begin{macrocode}
412 \def\git@formatCommitTime#1-#2-#3 #4:#5:#6 +#7\relax{&
413 \formattime{#4}{#5}{#6}&
414 \ifgit@opt@ShowTimeZone&
415 \space(+#7\unskip)&
416 \fi&
417 }
418 % \end{macrocode}
419 %\end{macro}
420 %
421 %\begin{macro}{\gitcommitdate}
422 % Get a commit date. If \gitopt{formatDate} is set,
423 % \cs{git@formatCommitDate} will be used. If \gitopt{formatTime} is set, and
424 % \gitopt{formatDate} is unset, \cs{git@formatCommitTime} will be used.
425 % \gitoptions{directory,formatDate,formatTime,revision,showTimeZone}
426 %
427 % \begin{macrocode}
428 \newcommand{\gitcommitdate}[1][]{&
429 \git@commitdate[#1]&
430 \ifgit@opt@FormatDate&
431 \expandafter\git@formatCommitDate\git@rawresult\relax&
432 \ifgit@opt@FormatTime&
433 \git@opt@FormatInterDateTime&
434 \expandafter\git@formatCommitTime\git@rawresult\relax&
435 \fi
436 \else\ifgit@opt@FormatTime&
437 \expandafter\git@formatCommitTime\git@rawresult\relax&
438 \else
439 \git@result&
440 \fi\fi&
441 }
442 % \end{macrocode}
443 %\end{macro}
444 %
445 %\begin{macro}{\git@commitdate}
446 % Like \cs{gitcommitdate}, but does not return the output.
447 % \begin{macrocode}
448 \newcommand{\git@commitdate}[1][]{&
449 \pgfkeys{/git,default,#1}&
450 \git@command{git log -n 1 --format=%ai
451 \git@opt@Revision\git@space -- \git@opt@File}&
452 }
453 % \end{macrocode}
454 %\end{macro}
455 %
456 %\begin{macro}{\gitcommitauthor}
457 % Get a commit author.
458 % \gitoptions{directory,revision}
459 %
460 % \begin{macrocode}
461 \newcommand{\gitcommitauthor}[1][]{&
462 \git@commitauthor[#1]\git@result}
463 % \end{macrocode}
464 %\end{macro}
465 %
466 %\begin{macro}{\git@commitauthor}
467 % Like \cs{gitcommitauthor}, but does not return the output.
468 % \begin{macrocode}
469 \newcommand{\git@commitauthor}[1][]{&
470 \pgfkeys{/git,default,#1}&
471 \git@command{git log -n 1 --format='%an <%ae>'
472 \git@opt@Revision\git@space -- \git@opt@File}&
473 }
474 % \end{macrocode}
475 %\end{macro}
476 %
477 %\begin{macro}{\gitcommitauthorname}
478 % Get a commit author's name.
479 % \gitoptions{directory,revision}
480 %
481 % \begin{macrocode}
482 \newcommand{\gitcommitauthorname}[1][]{&
483 \git@commitauthorname[#1]\git@result}
484 % \end{macrocode}
485 %\end{macro}
486 %
487 %\begin{macro}{\git@commitauthorname}
488 % Like \cs{gitcommitauthorname}, but does not return the output.
489 % \begin{macrocode}
490 \newcommand{\git@commitauthorname}[1][]{&
491 \pgfkeys{/git,default,#1}&
492 \git@command{git log -n 1 --format=%an
493 \git@opt@Revision\git@space -- \git@opt@File}&
494 }
495 % \end{macrocode}
496 %\end{macro}
497 %
498 %\begin{macro}{\gitcommitauthoremail}
499 % Get a commit author's email address.
500 % \gitoptions{directory,revision}
501 %
502 % \begin{macrocode}
503 \newcommand{\gitcommitauthoremail}[1][]{&
504 \git@commitauthoremail[#1]\git@result}
505 % \end{macrocode}
506 %\end{macro}
507 %
508 %\begin{macro}{\git@commitauthoremail}
509 % Like \cs{gitcommitauthoremail}, but does not return the output.
510 % \begin{macrocode}
511 \newcommand{\git@commitauthoremail}[1][]{&
512 \pgfkeys{/git,default,#1}&
513 \git@command{git log -n 1 --format=%ae
514 \git@opt@Revision\git@space -- \git@opt@File}&
515 }
516 % \end{macrocode}
517 %\end{macro}
518 %
519 %\begin{macro}{\git@commitparent}
520 % Get the hash of the first parent.
521 % \begin{macrocode}
522 \newcommand{\git@commitparent}[1][]{&
523 \pgfkeys{/git,default,#1}&
524 \git@command{git log -n 1 --format=%p
525 \git@opt@Revision\git@space -- \git@opt@File
526 | cut -d' ' -f2}&
527 }
528 % \end{macrocode}
529 %\end{macro}
530 %
531 %\begin{macro}{\gitchanges}
532 % Record the full \git{} commit history (following first parents using
533 % \cs{git@commitparent}) using \cs{changes}.
534 % \begin{macrocode}
535 \newcommand{\gitchanges}[1][]{&
536 \git@changes[#1]{HEAD}
537 }
538 % \end{macrocode}
539 %\end{macro}
540 %
541 %\begin{macro}{\git@changes}
542 % Like \cs{gitchanges}, but accepts an extra argument for the revision.
543 % \begin{macrocode}
544 \newcommand{\git@changes}[2][]{&
545 \edef\git@@revision{#2}&
546 \git@commithash[revision=\git@@revision]&
547 \edef\git@@thishash{\git@rawresult}&
548 \git@command{git log -n 1 --format=%ad --date=short \git@opt@Revision}&
549 \edef\git@@thisdate{\git@rawresult}&
550 \git@commitmsg[revision=\git@@revision]&
551 & TODO: this removes '=' characters because they break \changes, but the real
552 & solution would be to put something back that restores these characters.
553 \StrSubstitute[0]{\git@rawresult}{=}{}[\git@@thismsg]&
554 \changes{\git@@thisdate\unskip: \git@@thishash}{\git@@thisdate}{\git@@thismsg}&
555 \git@commitparent[revision=\git@@revision]&
556 \let\git@@parent\git@rawresult&
557 \setbox0=\hbox{\git@@parent\unskip}\ifdim\wd0=0pt
558 \else&
559 \git@changes{\git@@parent}&
560 \fi&
561 }
562 % \end{macrocode}
563 %\end{macro}
564 %
565 %Reset the catcodes for \verb$%$ and \verb$&$:
566 % \begin{macrocode}
567 \catcode`\&=4\catcode`\%=14
568 % \end{macrocode}
569 %
570 % \begin{comment}
571 %</package>
572 % \end{comment}
573 %
574 %\Finale
575 \endinput