\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}, } \end{filecontents} \usepackage[% backend=biber, sortlocale=de_DE, style=authoryear, bibencoding=UTF8, block=space, autocite=inline, language=ngerman, ]{biblatex} \addglobalbib{gitfile-info.bib} \renewcommand*{\mkbibnamelast}{\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} \begin{document} \title{Gitfile-Info\newline\newline \LaTeX-Paket zum Auslesen von git Ver"-sions"-in"-for"-ma"-tion"-en für eine Datei\newline\newline \LaTeX-package for reading git commit info for specific files } \author{Andr\'e Hilbig -- \href{mailto:mail@andrehilbig.de}{mail@andrehilbig.de}} \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, anderen Nutzern oder Entwicklern 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 verschiedene 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] Veröffentlichung \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 Paket- und Klassendateien \begin{lstlisting}[gobble=12,numbers=none,language=bash,% linewidth=0.7\textwidth,resetmargins=false] latex 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/bewerbung/| an. \item Außerdem werden die drei Python-Scripte \verb|gfi-run|, \verb|post-commit| und \verb|post-merge| 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 Hooks \verb|post-commit| und \verb|post-merge| müssen innerhalb des Repositories im Verzeichnis \verb|.git/hooks| als ausführbare Dateien 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| 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 # eine spezielle *.tex-Datei aktualisieren python gfi-run datei.tex \end{lstlisting} \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| 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| 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. \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| 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} \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| 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 sollen, 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 in 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 des \wM{gfiSet*}-Makros. \DescribeMacro{\gfiSetDate} |\gfiSetDate|\marg{Tag}\marg{Monat}\marg{Jahr}\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. Entsprechend werden dadurch 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! \begin{lstlisting}[gobble=8,numbers=none,language=python,% linewidth=0.7\textwidth,resetmargins=false] locale.setlocale(locale.LC_ALL, 'de_DE') \end{lstlisting} \subsubsection{gfi-run} Das \verb|gfi-run| 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 # eine spezielle *.tex-Datei aktualisieren python gfi-run 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]{gfi-run} \subsubsection{post-commit} 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]{post-commit} \subsubsection{post-merge} 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]{post-merge} \clearpage \addcontentsline{toc}{section}{Literatur} \printbibliography \end{document}