ahilbig/gitfile-info
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Kleinere Doku Fehler überarbeitet, Literatur hinzugefügt

Browse Source
This commit is contained in:
André Hilbig
2016-06-27 22:17:53 +02:00
parent 72d37c8242
commit 96c6777a68
5 changed files with 69 additions and 38 deletions
Download Patch File Download Diff File Expand all files Collapse all files

19
build
View File

@@ -3,9 +3,10 @@ echo "===================================================================" >> bu
echo "=+-Lauf vom `date +%Y-%m-%d:%H:%M:%S`----------------------------------+=" >> build.log
sty2dtx -O -c gitfile-info.sty -o gitfile-info/gitfile-info.sty >> build.log
echo "=+-sty2dtx abgeschlossen-----------------------------------------+=" >> build.log
cp -v gfi-run gitfile-info/
cp -v post-commit gitfile-info/
cp -v post-merge gitfile-info/
cp -v gfi-run.py gitfile-info/
cp -v post-commit.py gitfile-info/
cp -v post-merge.py gitfile-info/
cp -v dokumentation.gfi gitfile-info/gitfile-info.gfi
sed "s/Version: [0-9].[0-9]*/Version: $1/1" README > /tmp/output.readme
sed "s/Last Change: [0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]/Last Change: `date +%Y-%m-%d`/1" /tmp/output.readme > output.readme
mv -v output.readme gitfile-info/README
@@ -13,13 +14,13 @@ echo "=+-Kopieren und Anpassen abgeschlossen---------------------------+=" >> bu
cd gitfile-info
echo "=+-Packe DTX-----------------------------------------------------+=" >> build.log
../makedtx.pl -src "(.*)\.sty=>\1.sty" -doc ../dokumentation.tex \
-src "gfi-run=>gfi-run" -src "post-commit=>post-commit" -src "post-merge=>post-merge" \
-macrocode "gfi-run" -macrocode "post-commit" -macrocode "post-merge" \
-setambles "gfi-run=>\\nopreamble\\nopostamble" -setambles "post-commit=>\\nopreamble\\nopostamble" \
-setambles "post-merge=>\\nopreamble\\nopostamble" \
-comment "gfi-run" -comment "post-commit" -comment "post-merge" \
-src "gfi-run.py=>gfi-run.py" -src "post-commit.py=>post-commit.py" -src "post-merge.py=>post-merge.py" \
-macrocode "gfi-run.py" -macrocode "post-commit.py" -macrocode "post-merge.py" \
-setambles "gfi-run.py=>\\nopreamble\\nopostamble" -setambles "post-commit.py=>\\nopreamble\\nopostamble" \
-setambles "post-merge.py=>\\nopreamble\\nopostamble" \
-comment "gfi-run.py" -comment "post-commit.py" -comment "post-merge.py" \
-date "`date +%Y-%m-%d:%H:%M:%S` -- Version $1" \
-author "André Hilbig, mail@andrehilbig.de" -codetitle "Implementation" gitfile-info
-author "André Hilbig, mail@andrehilbig.de" -codetitle "Code" gitfile-info
pdflatex gitfile-info.dtx
CHECKSUM=$(grep "The checksum should be" gitfile-info.log | grep -o "[0-9]*")
echo "The checksum is: $CHECKSUM"

88
dokumentation.tex
View File

@@ -18,6 +18,31 @@
url = {https://github.com/gitpython-developers/GitPython},
urldate = {2016-06-23},
}
@electronic{datenumber,
author = "Jörg-Michael Schrö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,
@@ -242,20 +267,21 @@ pdftitle = {\LaTeX-package for reading git commit info for specific files}
\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/|
\verb|~/texmf/tex/latex/gitfile-info/|
an.
\item Außerdem werden die drei Python-Scripte
\verb|gfi-run|, \verb|post-commit| und \verb|post-merge|
\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 Hooks \verb|post-commit| und \verb|post-merge| müssen innerhalb des Repositories im
Verzeichnis \verb|.git/hooks| als ausführbare Dateien platziert werden.
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.
@@ -263,17 +289,17 @@ pdftitle = {\LaTeX-package for reading git commit info for specific files}
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
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
python gfi-run.py
# eine spezielle *.tex-Datei aktualisieren
python gfi-run datei.tex
python gfi-run.py datei.tex
\end{lstlisting}
Die Scripte sollten in einer Standard \texttt{texlive}"~Installation unter dem Pfad
@@ -286,24 +312,26 @@ pdftitle = {\LaTeX-package for reading git commit info for specific files}
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
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| 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.
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.
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| per Hand aufgerufen
\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}).
@@ -340,6 +368,8 @@ pdftitle = {\LaTeX-package for reading git commit info for specific files}
\item[\wM{gfiGetCommitAbr}] gibt die Kurzform des letzten Commits zurück.
\end{description}
Ergänzend sei auf das
\subsection{Versionsinfo}
\DescribeMacro{\gfiInfo}
Sofern eine kleine Zusammenfassung der aktuellen Datei gezeigt werden soll, kann dazu das Makro
@@ -386,10 +416,10 @@ pdftitle = {\LaTeX-package for reading git commit info for specific files}
\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.
Ä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}
@@ -443,15 +473,15 @@ pdftitle = {\LaTeX-package for reading git commit info for specific files}
\end{lstlisting}
\subsubsection{gfi-run}
Das \verb|gfi-run| kann sowohl zur Initialisierung als auch zur erzwungenen Aktualisierung
\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
python gfi-run.py
# eine spezielle *.tex-Datei aktualisieren
python gfi-run datei.tex
python gfi-run.py datei.tex
\end{lstlisting}
Das Script sucht dabei mithilfe von \verb|git ls-files| nach allen unter Versionsverwaltung
@@ -459,24 +489,24 @@ pdftitle = {\LaTeX-package for reading git commit info for specific files}
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}
\lstinputlisting[language=python,title=Quelltext von gfi-run.py]{gfi-run.py}
\subsubsection{post-commit}
\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]{post-commit}
\lstinputlisting[language=python,title=Quelltext von post-commit.py]{post-commit.py}
\subsubsection{post-merge}
\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]{post-merge}
\lstinputlisting[language=python,title=Quelltext von post-merge.py]{post-merge.py}
\addcontentsline{toc}{section}{Literatur}
\printbibliography[title=Weiterführende Quellen]

0
gfi-run → gfi-run.py
View File

0
post-commit → post-commit.py
View File

0
post-merge → post-merge.py
View File