\documentclass[a4paper]{ltxdoc} \usepackage[utf8]{inputenc} \usepackage[T1]{fontenc} \usepackage[english,ngerman]{babel} \usepackage{xparse,xargs} \usepackage{newfloat} \usepackage[usenames,dvipsnames,svgnames,table]{xcolor} \definecolor{blau}{rgb}{0,0,0.75} \definecolor{orange}{rgb}{0.8,0.3,0} \begin{filecontents}{gitfile-info.bib} @electronic{gitpython, editor = "gitpython-developers", month = {Jun}, year = "2016", title = "GitPython", subtitle = "GitPython is a python library used to interact with Git repositories", url = {https://github.com/gitpython-developers/GitPython}, urldate = {2016-06-23}, } @electronic{datenumber, author = "J{\"o}rg-Michael Schr{\"o}der", month = {Aug}, year = "2001", title = "The datenumber.sty package v0.02", url = {http://www.ctan.org/pkg/datenumber}, urldate = {2016-06-27}, } @electronic{svninfo, author = "Achim Brucker", month = {Mar}, year = "2010", title = "The svninfo package", url = {http://www.ctan.org/pkg/svninfo}, urldate = {2016-06-27}, } @electronic{gitinfo2, author = "Brent Longborough", month = {Nov}, year = "2015", title = "gitinfo2.sty", subtitle = "A package for accessing metadata from the git dvcs", url = {http://www.ctan.org/pkg/gitinfo2}, urldate = {2016-06-27}, } \end{filecontents} \usepackage[% backend=biber, sortlocale=de_DE, style=authoryear, bibencoding=UTF8, block=space, autocite=inline, language=ngerman, ]{biblatex} \addglobalbib{gitfile-info.bib} \renewcommand*{\mkbibnamefamily}{\textsc} \DeclareCiteCommand{\citeauthorfull} {% \boolfalse{citetracker}% \boolfalse{pagetracker}% \usebibmacro{prenote}} {\ifciteindex% {\indexnames{labelname}} {}% \printnames[first-last]{author}} {\multicitedelim} {\usebibmacro{postnote}} \usepackage{hyperref} \hypersetup{% pdftitle = {\LaTeX-package for reading git commit info for specific files} pdfsubject = {}, % pdfkeywords = {LaTeX,CTAN,git,fileinfo,version,control}, % pdfauthor = {Andr\'e Hilbig}, % colorlinks = true, % hypertexnames = true, % linkcolor=blau, % filecolor=orange, % citecolor=blau, % menucolor=orange, % urlcolor=orange, % breaklinks=true % } \usepackage{graphics,graphicx,textcomp} \usepackage{placeins,float,caption,prettyref} \usepackage{pdfpages,listings,xspace} \usepackage{amssymb,multicol,pdflscape} \usepackage[german=guillemets]{csquotes} \newrefformat{sec}{Abschnitt\,\ref{#1}, S.\,\pageref{#1}} \newrefformat{paket}{Paket~\ref{#1}, S.\,\pageref{#1}} \newrefformat{klasse}{Klasse~\ref{#1}, S.\,\pageref{#1}} \newrefformat{fig}{Abb.\,\ref{#1}} \newrefformat{tab}{Tab.\,\ref{#1}} \newcommand{\refMacro}[1]{Makro \texttt{\textbackslash#1}, S.\,\pageref{#1}} \DisableCrossrefs \makeatletter \makeatother \lstset{ % language=[LaTeX]TeX, basicstyle=\small, numbers=left, numberstyle=\footnotesize, stepnumber=1, numbersep=5pt, backgroundcolor=\color{Peach!30!white}, showspaces=false, showstringspaces=false, showtabs=false, frame=single, tabsize=2, resetmargins=true, captionpos=b, title={}, caption={}, breaklines=true, breakautoindent=true, prebreak=\mbox{ $\curvearrowright$}, postbreak=\mbox{$\rightsquigarrow$ }, linewidth=\columnwidth, breakatwhitespace=true, numberstyle=\tiny\color{gray}, keywordstyle=\color{OliveGreen}\textbf, commentstyle=\color{gray}\itshape, stringstyle=\color{orange}, morekeywords={ minisec, subsection, glqq, grqq, euro, href, gfiGetAuthorName, gfiGetAuthorMail, gfiGetCommit, gfiGetCommitAbr, gfiGetDate, gfiGetMin, gfiGetHour, gfiGetDay, gfiGetMonth, gfiGetYear, gfiInfo, }, literate=% {Ö}{{\"O}}1 {Ä}{{\"A}}1 {Ü}{{\"U}}1 {ß}{\ss}2 {ü}{{\"u}}1 {ä}{{\"a}}1 {ö}{{\"o}}1 {»}{{\frqq}}4 {«}{{\flqq}}4 {~}{$\sim$}1 } \newcommand{\wM}[1]{\texttt{\textbackslash#1}} \xspaceaddexceptions{\guillemotright,\guillemotleft} \usepackage{gitfile-info} \usepackage{scrpage2} \pagestyle{scrheadings} \ifoot{Commit: \gfiGetCommitAbr} \ofoot{\thepage} \ihead{\gfiGetAuthorName} \ohead{Stand: \gfiGetDate} \CheckSum{0} \makeatletter \newcommand{\@subtitleA}{} \newcommand{\@subtitleB}{} \newcommand{\subtitle}[2]{% \renewcommand{\@subtitleA}{#1} \renewcommand{\@subtitleB}{#2} } \renewcommand\@maketitle{% \hfil \begin{minipage}{0.8\textwidth} \centering \vskip 2em \let\footnote\thanks {\LARGE \@title \par } \vskip 1.5em {\Large \@subtitleA \par } \vskip 1.5em {\Large \@subtitleB \par } \vskip 1.5em {\large \@author \par} \end{minipage} \hfil \vskip 1em \par } \makeatother \begin{document} \title{\textbf{Gitfile-Info}} \subtitle{% \LaTeX-Paket zum Auslesen von git Ver"-sions"-in"-for"-ma"-tion"-en für eine Datei }{% \LaTeX-package for reading git commit info for a specific file% } \author{Andr\'e Hilbig\\ \href{mailto:mail@andrehilbig.de}{mail@andrehilbig.de} -- \href{http://www.andrehilbig.de/u/gfi}{andrehilbig.de/u/gfi}} \date{\gfiGetDay.\gfiGetMonth.\gfiGetYear} \maketitle \begin{abstract} \foreignlanguage{english}{ If you are using git to control versions of \LaTeX-files, you may want to show yourself or other users or devs the current version of the file, information about the author and last edited date. All packages for git known make that kind of information available for the whole repository. But sometimes you have a lot of files within the same repository in different versions, from different authors etc. Perhaps you also split up a big project in small files and want to show within the document who had edited what. This package gives you the opportunity to do so. } Wenn Versionen von \LaTeX-Dateien mit git kontrolliert werden, dann kommt es vor, dass für einen selbst, andere Nutzern oder Entwickler der aktuelle Entwicklungsstand der Datei, Hinweise zum Autor und dem Datum der letzten Bearbeitung im PDF gezeigt werden sollen. Mir bekannte Pakete können zwar den Stand des Repositories auslesen, jedoch nicht für eine bestimmte Datei unterscheiden. Allerdings wird manchmal mit vielen Dateien in einem Repository gearbeitet, die jeweils in verschiedenen Versionen vorliegen. Möglicherweise soll auch ein großes Projekt in mehrere \TeX-Dateien aufgeteilt werden. Dann soll dennoch für jede einzelne Datei die Versionsinfo angezeigt werden können. Dieses Paket soll diese Funktionalität liefern. \end{abstract} \begin{multicols}{2} \tableofcontents \end{multicols} \section{Änderungen} \begin{description} \item[v0.1] Intialisierung und erste Veröffentlichung \item[v0.2] Dokumentation auf CTAN inkludiert \item[v0.3] Pfad der Scripte in texlive in der Dokumentation aktualisiert -- Pythonscripte erzwingen Py3 und geben Fehler bei falscher Lokalisierung aus. \end{description} \section{Installation} \subsection{Systemanforderungen} Um die Informationen über einzelne Dateien aus dem git auszulesen, müssen entsprechende Scripte bzw. Hooks innerhalb des Repositories platziert werden. Damit eine möglichst breite Nutzbarkeit möglich ist, habe ich mich dazu entschieden mit Python und der gitpython-Bibliothek zu arbeiten. \begin{itemize} \item Python>=3 \item gitpython: \fullcite{gitpython} (kann über \verb|pip| installiert werden) \end{itemize} \textbf{Hinweis:} Die Scripte werden in erster Linie für Unix-basierte Betriebssysteme geschrieben. Support für andere Systeme kann und möchte ich nicht leisten. \subsection{Automatische Installation} Das Paket ist über \verb|CTAN| verfügbar und kann so mit dem \verb|tlmgr| bzw. der Paketverwaltung des Betriebssystems\footnote{Leider halten viele Distributionen ihre \LaTeX-Installationen nicht aktuell. Daher wird empfohlen die direkten Quellen, etwa von |texlive|, zu verwenden.} abgerufen werden. \subsection{Manuelle Installation} Falls eine automatisierte Installation nicht möglich ist, können die Pakete auch manuell installiert werden. Es wird jedoch empfohlen, eine aktuelle Distribution zu verwenden, etwa \verb|texlive2016|. Für Versionen davor kann keine Kompatibilität gewährleistet werden. Zur Installation werden die Dateien \verb|gitfile-info.ins| und \verb|gitfile-info.dtx| benötigt. \begin{itemize} \item Erzeugung der Paketdateien und Dokumentation \begin{lstlisting}[gobble=12,numbers=none,language=bash,% linewidth=0.7\textwidth,resetmargins=false] latex gitfile-info.ins latexmk -pdf gitfile-info.dtx \end{lstlisting} \item Die erzeugte Paketdatei (*.sty) muss in einem für \TeX\ lesbarem Verzeichnis platziert werden. Für eine lokale Installation bietet sich dafür \verb|~/texmf/tex/latex/gitfile-info/| an. \item Außerdem werden die drei Python-Scripte \verb|gfi-run.py|, \verb|post-commit.py| und \verb|post-merge.py| erstellt. Diese Dateien müssen im Repository platziert werden (vgl. \prettyref{sec:installation-git}). \end{itemize} \subsection{Einrichtung des Repositories}\label{sec:installation-git} Die beiden Scripte \verb|post-commit.py| und \verb|post-merge.py| müssen innerhalb des Repositories im Verzeichnis \verb|.git/hooks| als ausführbare Dateien unter den Namen \verb|post-commit| bzw. \verb|post-merge| platziert werden. \begin{description} \item[\verb|post-commit|] wird bei jedem Commit ausgeführt (nachdem der Commit vollständig beendet ist) und schreibt für die veränderten \TeX-Dateien Änderungen in eine Hilfsdatei. \item[\verb|post-merge|] wird nach jedem merge (erfolgreich und nicht erfolgreich -- explizit auch nach einem pull) ausgeführt, um Veränderungen in die Hilfsdatei einzutragen. \end{description} Außerdem sollte das Script \verb|gfi-run.py| möglichst für jeden Nutzer im Repository ausführbar platziert werden. Wird das Script ohne Parameter ausgeführt, liest es sämtliche unter Versionsverwaltung stehende Dateien aus und erstellt die passenden Hilfsdateien. Wird dem Script eine \TeX-Datei (inkl. Endung) übergeben, wird die Hilfsdatei für diese spezielle Datei neu erstellt. \begin{lstlisting}[gobble=10,numbers=none,language=bash,% linewidth=0.7\textwidth,resetmargins=false] # alle *.tex-Dateien aktualisieren python gfi-run.py # eine spezielle *.tex-Datei aktualisieren python gfi-run.py datei.tex \end{lstlisting} Die Scripte sollten in einer Standard \texttt{texlive}"~Installation unter dem Pfad \verb|…/texmf-dist/doc/support/gitfile-info/| gefunden werden können. Bei einer manuellen Installation sollten die Scripte mit erstellt worden sein. \textbf{Hinweis:} Die drei Dateien sollten Nutzern zur Verfügung gestellt werden. Typischerweise sind sie nach einem Clone nicht im Baum enthalten. Jeder Nutzer muss sich die Hooks selbstständig einrichten -- außer es werden entsprechende Konfigurationen festgelegt. Außerdem muss in der \verb|*.gitignore| der Filter \verb|*.gfi| festgelegt werden, da die Hilfsdateien in \textbf {keinem} Fall unter Versionsverwaltung stehen dürfen. Daher muss ein Nutzer nach einem \textit{frischen} Clone das Script \verb|gfi-run.py| aufrufen, um alle Hilfsdateien lokal zu erstellen. \section{Funktionsweise} \subsection{Vorüberlegungen} Zunächst stand die Überlegung im Raum, Meta-Daten ähnlich wie beim Paket \verb|svninfo| \autocite[vgl.][]{svninfo} direkt in die betreffenden \TeX-Dateien einzutragen. Dadurch wird jedoch der Arbeitsstand verändert und der eingetragene Commit ist nicht mehr aktuell. Es müsste ein erneuter Commit erfolgen usw. Hier gäbe es die Möglichkeit, automatisierte Commits zu erstellen. Diese würden jedoch das Repository aufblähen. Daher entschied ich mich dafür, die passenden Meta-Daten in eine Hilfsdatei (\verb|*.gfi|) einzutragen. Hier können per simplem \LaTeX-Befehl Metadaten eingegeben werden. Das bereits bestehende Paket gitinfo2 \autocite[vgl.][]{gitinfo2} konnte nicht benutzt werden, da es das gesamte Repository ausliest und nicht zwischen einzelnen Dateien unterscheidet. \subsection{Umsetzung} Bei jedem Commit oder Pull gehen die Scripte alle geänderten \TeX-Dateien durch und aktualisieren die entsprechenden Hilfsdateien. Hier werden \textbf{nur} Dateien mit der Endung \verb|*.tex| berücksichtigt! Bei Problemen kann das Script \verb|gfi-run.py| per Hand aufgerufen werden, um eine Aktualisierung zu erzwingen (vgl. \prettyref{sec:installation-git}). \section{Nutzung des Pakets} Alle Makros geben immer die Versionsinformationen für die \textit{aktuelle} Datei zurück, sofern diese geeignet geladen wurde (vgl. \prettyref{sec:nutzung-include}). Das Paket wird dazu in der Präambel des Dokumentes geladen. \begin{lstlisting}[gobble=8,numbers=none,% linewidth=0.7\textwidth,resetmargins=false] \usepackage{gitfile-info} \end{lstlisting} Weitere Optionen müssen nicht angegeben werden. Sofern notwendige Hilfsdateien mit der Endung \verb|*.gfi| noch nicht vorhanden sind, werden alle Makros mit Standardwerten belegt und eine Warnung ausgegeben. \subsection{Auslesen der Metadaten} \DescribeMacro{\gfiGet} Über die \verb|\gfiGet*|-Makros können die Metadaten aus dem Repository ausgelesen werden. \begin{description} \item[\wM{gfiGetDay}] gibt den Tag der letzten Änderung als zweistellige Ziffer zurück. \item[\wM{gfiGetMonth}] gibt den Monat der letzten Änderung als zweistellige Ziffer zurück. \item[\wM{gfiGetYear}] gibt das Jahr der letzten Änderung als zweistellige Ziffer zurück. \item[\wM{gfiGetHour}] gibt die Stunde der letzten Änderung als zweistellige Ziffer zurück. \item[\wM{gfiGetMin}] gibt die Minute der letzten Änderung als zweistellige Ziffer zurück. \item[\wM{gfiGetDate}] gibt das volle Datum der letzten Änderung mit Uhrzeit im Format \verb|dd. Monat yyyy HH:MM| zurück\footnote{Das Format wird durch die Scripte vorgegeben und muss in diesen ggfs. angepasst werden, sofern eine Lokalisierung gewünscht ist (vgl. \prettyref{sec:implementierung-scripte})} \item[\wM{gfiGetAuthorName}] gibt den Namen des Autors der letzten Änderung zurück. \item[\wM{gfiGetAuthorMail}] gibt die E-Mailadresse des Autors der letzten Änderung zurück. \item[\wM{gfiGetCommit}] gibt den Hash des letzten Commits zurück. \item[\wM{gfiGetCommitAbr}] gibt die Kurzform des letzten Commits zurück. \end{description} Ergänzend sei auf das Paket datenumber \autocite[vgl.][]{datenumber} verwiesen. Damit ist es möglich obige Makros für Tag, Monat und Jahr zwischen lokalisierten Monatsbezeichnungen usw. zu konvertieren. \subsection{Versionsinfo} \DescribeMacro{\gfiInfo} Sofern eine kleine Zusammenfassung der aktuellen Datei gezeigt werden soll, kann dazu das Makro |\gfiInfo|\oarg{Hashlänge}\oarg{Datumsformat}\oarg{Autorformat}\oarg{tcolorbox}\\ benutzt werden. Sofern alle optionalen Argumente leer gelassen werden, wird der lange Hash, das Standard \wM{gfiGetDate} und der Name des Autors als Hyperlink auf die E-Mailadresse in einer |tcolorbox| mit dem Namen |gfiInfoBox| ausgegeben. \gfiInfo \begin{description} \item[Hashlänge] kann durch Angabe von |abr| als verkürzter Hash ausgegeben werden. Standard: lang. \item[Datumsformat, Autorformat] können jeweils beliebige \TeX-Befehle enthalten. Standard: langes Datum und Name als Hyperlink. \item[tcolorbox] kann einer beliebigen über |\newtcolorbox{}| eingeführten tcolorbox entsprechen. Standard: |gfiInfoBox|. \end{description} \DescribeMacro{gfiInfoBox} Durch Verwendung der definierten Box \verb|gfiInfoBox| können auch beliebige andere Zusammenstellungen erstellt werden. \begin{lstlisting}[gobble=6,] \begin{gfiInfoBox} \vspace{1mm} Die letzte Änderung wurde durch den Autor \gfiGetAuthorName\ (\href{mailto:\gfiGetAuthorMail}{\gfiGetAuthorMail}) am \gfiGetDay.\gfiGetMonth.\gfiGetYear\ um \gfiGetHour:\gfiGetMin\,Uhr commited. Die letzte Änderung hat den Commit \gfiGetCommitAbr. \vspace{1mm} \end{gfiInfoBox} \end{lstlisting} \begin{gfiInfoBox} \vspace{1mm} Die letzte Änderung wurde durch den Autor \gfiGetAuthorName\ (\href{mailto:\gfiGetAuthorMail}{\gfiGetAuthorMail}) am \gfiGetDay.\gfiGetMonth.\gfiGetYear\ um \gfiGetHour:\gfiGetMin\,Uhr commited. Die letzte Änderung hat den Commit \gfiGetCommitAbr. \vspace{1mm} \end{gfiInfoBox} \subsection{Laden weiterer \TeX-Dateien}\label{sec:nutzung-include} Ähnlich wie im Paket \verb|svninfo| \autocite[vgl.][]{svninfo} soll auch die Aufsplittung eines größeren Projekts in mehrere Teildateien mit den entsprechenden Versionen der einzelnen Dateien auslesbar sein. Dafür müssen diese Dateien ebenfalls die Endung \verb|*.tex| haben, um von den Scripten erkannt zu werden. \DescribeMacro{gfiInclude} \DescribeMacro{gfiInput} Im Hauptdokument werden die Metadaten automatisch beim Beginn geladen. Sofern eine weitere Datei per \wM{include} oder \wM{input} geladen werden soll, müssen dafür die Befehle |\gfiInclude|\marg{Datei} bzw. |\gfiInput|\marg{Datei}\\ genutzt werden. Die Endung der Datei sollte dabei \textbf{nicht} mit angegeben werden. Intern werden die jeweiligen Befehle zum Laden einer weiteren Datei entsprechend genutzt. Außerdem wird die zugehörige Hilfsdatei eingebunden, um die notwendigen Metadaten zu erhalten. Nachdem die inkludierte Datei vollständig bearbeitet wurde, werden die Metadaten der vorherigen bzw. dann aktuellen Datei geladen. Es ist auch möglich, beliebige Verschachtelungen vorzunehmen. \section{Implementierung} \subsection{Paket} Das Paket lädt automatisch die zugehörige Hilfsdatei eines Hauptdokuments über den entsprechenden \wM{jobname}. Der Nutzer musst hierfür keine Anpassung vornehmen. Sollten weitere Dokumente eingebunden werden, müssen die bereitgestellten Befehle genutzt werden, sofern die zugehörigen Versioninformationen geladen werden sollen (vgl. \prettyref{sec:nutzung-include}). Die Hilfsdatei trägt den selben Namen, wie die zugehörige \TeX-Datei, und enthält passende Aufrufe der \wM{gfiSet*}-Makros. \DescribeMacro{\gfiSetDate} |\gfiSetDate|\marg{Tag}\marg{Monat}\marg{Jahr}\\ \hspace*{5em}\marg{Stunde}\marg{Minute}\marg{Lokalisierte Langfassung}\\ Tag, Monat, Stunde und Minute sind jeweils als zweistellige Ziffern einzulesen. Das Jahr wird als vierstellige Ziffer eingelesen und in der Langassung kann beliebiger Text stehen, der einer durch die Scripte lokalisierten Version entspricht. Dadurch werden die \wM{gfiGet*}-Makros definiert. \wM{gfiGetDate} entspricht der Langfassung. \DescribeMacro{\gfiSetAuthor} |\gfiSetAuthor|\marg{Name}\marg{E-Mail}\\ Name und E-Mail sollten die zugehörigen Daten enthalten und werden mit den \wM{gfiGet*}-Makros verknüpft. \DescribeMacro{\gfiSetCommit} |\gfiSetCommit|\marg{Hash}\marg{Hash-Abr}\\ Die volle Fassung des Commits wird im Hash, die kurze Version im Hash-Abr eingegeben und entsprechend mit \wM{gfiGet*} verknüpft. \subsection{Scripte}\label{sec:implementierung-scripte} Die Scripte sind auf deutsche Monatsbezeichnungen eingestellt. Sofern hier eine andere Lokalisierung gewünscht wird, muss in \textit{allen} Scripten der entsprechende Eintrag in der Präambel geändert werden! Prinzipiell reicht es aus im ersten Block zu ändern, da bei einer individuellen Anpassungen Fehler nicht auftreten sollten. \begin{lstlisting}[gobble=8,numbers=none,language=python,% linewidth=0.7\textwidth,resetmargins=false] try: locale.setlocale(locale.LC_ALL, 'de_DE.utf8') except: try: locale.setlocale(locale.LC_ALL, 'de_DE') \end{lstlisting} \subsubsection{gfi-run.py} Das \verb|gfi-run.py| kann sowohl zur Initialisierung als auch zur erzwungenen Aktualisierung aller \TeX-Dateien benutzt werden. \begin{lstlisting}[gobble=12,numbers=none,language=bash,% linewidth=0.7\textwidth,resetmargins=false] # alle *.tex-Dateien aktualisieren python gfi-run.py # eine spezielle *.tex-Datei aktualisieren python gfi-run.py datei.tex \end{lstlisting} Das Script sucht dabei mithilfe von \verb|git ls-files| nach allen unter Versionsverwaltung stehenden Dateien und erstellt (überschreibend) aufgrund von \verb|git log| für jede Datei einzeln die passende Hilfsdatei mit den Metadaten. Wird eine Datei übergeben, so wird nicht geprüft, ob diese unter Verwaltung steht und eine Hilfsdatei (im Zweifel leer) erstellt. \lstinputlisting[language=python,title=Quelltext von gfi-run.py]{gfi-run.py} \subsubsection{post-commit.py} Der \verb|post-commit|-Hook von \verb|git| wird nach jedem Commit, der erfolgreich ausgeführt wurde, automatisch ausgeführt. Der Hook liest aus, welche Dateien sich verändert haben und ändert für die passenden \TeX-Dateien die Hilfsdateien mit den neuen Metadaten. Das Script sollte im Verzeichnis \verb|.git/hooks| ausführbar platziert werden. \lstinputlisting[language=python,title=Quelltext von post-commit.py]{post-commit.py} \subsubsection{post-merge.py} Der \verb|post-merge|-Hook von \verb|git| wird nach jedem Merge ausgeführt. Er wird auch bei einem nicht erfolgreichen Merge aufgerufen. Explizit bedeutet dies auch, dass nach jedem Pull das Script ausgeführt wird. Der Hook liest aus, welche Dateien sich verändert haben und ändert für die passenden \TeX-Dateien die Hilfsdateien mit den neuen Metadaten. Das Script sollte im Verzeichnis \verb|.git/hooks| ausführbar platziert werden. \lstinputlisting[language=python,title=Quelltext von post-merge.py]{post-merge.py} \addcontentsline{toc}{section}{Literatur} \printbibliography[title=Weiterführende Quellen] \end{document}