Julius Plenz – Blog

Lange in Planung, aber nun ist sie endlich lieferbar: Die zweite, überarbeitete Auflage des Git-Buchs von Valentin und mir. Da ich gerade nicht am Lande bin, habe ich das Buch noch nicht in den Händen gehalten, aber Valentin hat ein Foto gemacht, denn das Buch trägt das neue Git-Logo auf dem Cover:

Die erste Auflage war Mitte 2011 erschienen. Etwas mehr als drei Jahre später ist diese ausverkauft, und es hat sich so viel in Git verändert, dass es sich lohnt, den alten Text nicht bloß nachzudrucken, sondern aufzuarbeiten (und die Fehler zu korrigieren). Ich zitiere aus dem Vorwort:

Wir haben uns in der 2. Auflage darauf beschränkt, die Veränderungen in der Benutzung von Git, die bis Version 2.0 eingeführt wurden, behutsam aufzunehmen – tatsächlich sind heute viele Kommandos und Fehlermeldungen konsistenter, so dass dies an einigen Stellen einer wesentlichen Vereinfachung des Textes entspricht. Eingestreut finden sich, inspiriert von Fragen aus Git-Schulungen und unserer eigenen Erfahrung, neue Hinweise auf Probleme, Lösungsansätze und interessante Funktionalitäten.

Teils sind die Änderungen nur minimal, und zielen darauf ab, Neulingen die „moderne“ Syntax der Kommandos beizubringen: Statt git commit --amend -C HEAD verwendet man nun zum Beispiel git commit --amend --no-edit, einen Merge bricht man mit git merge --abort ab (statt mit einem Hard-Reset), und das präferierte Pickaxe-Tool ist -G, nicht mehr -S (ein subtiler Unterschied!).

Teils werden neue Optionen und Best-Practices (push.default!) diskutiert, und neue, aber vermutlich wenig bekannte Optionen vorgestellt (z.B. die neuen Strategie-Optionen der Recursive-Merge-Strategie, mit denen man durch Whitespace-Unsinn verursachte Merge- oder Rebase-Konflikte häufig automatisch lösen kann).

Ein nicht unerheblicher Teil der Änderungen ist der Art, dass man sich als Autor freuen kann: Zum Beispiel haben wir den gesamten Teil über „Subtrees“ im Vergleich zu „Submodules“ umgeschrieben, so dass git subtree verwendet wird, das nun Teil von Git ist. Dadurch fallen mal eben ein Dutzend schwer zu merkender Kommandos weg und werden durch ein Subkommando ersetzt, das eine eigene Man-Page bereithält.

Wir haben über die drei Jahre hauptsächlich sehr positives Feedback zu dem Text erhalten. Insbesondere wurde von erfahrenen Anwendern häufig gelobt, dass wir komplexe Beispiele verwenden und „schnell zum Punkt kommen“. Der größte Kritikpunkt kam sicherlich aus der Windows-Fraktion: Hier haben sich einige Leute etwas irritiert gezeigt, wie sehr Unix-zentriert Textgestalt und Inhalte sind. Nach reiflicher Überlegung haben wir uns entschieden, nicht von diesem Kurs abzuweichen – insbesondere haben wir die Idee verworfen, eine Auswahl an GUI-Clients ausführlich zu thematisieren. Wir konnten in Git-Schulungen besonders mit „EGit“ (Eclipse) einiges an Erfahrung sammeln, und unser Fazit fällt im Wesentlichen negativ aus: Die Tools können nicht ansatzweise den Komfort und die Flexiblität des Original-Git bieten, haben an einigen wesentlichen Stellen Probleme – EGit kennt z.B. erst seit ein paar Monaten fetch.prune, und es gibt noch nicht mal einen Knopf dafür im Fetch-Dialog… wie soll man da effizient mit Branches arbeiten?! – und ändern sich außerdem noch viel zu schnell, als dass eine gedruckte Dokumentation helfen würde.

Eigentlich sollte die Neuauflage schon Ende des Sommers erscheinen. Dass es nun doch so lange gedauert hat, war vor allem technischen Gründen geschuldet: Die erste Auflage war in LaTeX geschrieben, doch mittlerweile hat der Open Source Press-Verlag auf das eigens entwickelte Publishing-System Textovia umgestellt, das AsciiDoc im Hintergrund verwendet.

Für die initiale Konvertierung von ca. 780 KB LaTeX-Quellcode sind wir dem Verlag sehr dankbar! Allerdings sind uns beim mehrmaligen konzentrierten Durchgehen an diversen Stellen noch übrig gebliebene LaTeX- und Konvertierungsartefakte aufgefallen, und so manchen einfachen LaTeX-Hack konnten wir nicht ohne Probleme in AsciiDoc umsetzen…

Die Umstellung auf das neue Format vereinfacht es immens, eine Print-Version parallel zu mehreren EBook-Versionen zu produzieren; insbesondere ist es aber so, dass nun im Print-Text keine Seitenzahlen mehr referenziert werden, sondern nur noch Abschnitt-Nummern. Wir hoffen, dass sich durch die Konvertierung nicht zu viele neue Fehler eingeschlichen haben.

Neben der Tatsache, dass die neue Auflage moderner und konsistenter ist, bietet sie eine ganz wesentliche Neuerung, die vielfach vermisst wurde: Jedes gedruckte Buch enthält auf der ersten Seite einen Code, mit dem man sich eine PDF-Version des Buches herunterladen kann: So ist das Buch angenehm auf Papier zu lesen, aber gleichzeitig leicht zu durchsuchen.

When writing the git book we faced a problem: when dealing with an example repository, how do you describe a directory structure?

Simply "writing" about it is the cheap apporach, although pretty stupid: most readers (including me) would skip over the paragraph. Later, they'd be confused when we'd refer to a specific property of the repository layout.

The intermediate approach was to simply paste the output of the tree unix command. That was hard to "parse" though, and didn't look well.

It is clear that a graphic representation of the directory structure is optimal. But: how? The easiest way would be to install some graphical application that can represent tree-structures, such as Nautilus. There are no upsides to this, but two minor downsides: it looks crappy, and it requires you to install some hundred megabytes of gnome-wtf-libs.

The major downside is this: If you want to re-do the screenshot, you'll need the same directory structure, the same setup, GNOME styles, same selection to grab, ... there is no easy way to automate this.

Not wanting to settle for the cheap way, what were the goals our solution had to meet?

1. can be understood at one glance (important)
2. can be automated and tracked in git (important)
3. does not eat up much space on the page
4. doesn't depend on colors

An alternative that came to my mind was to use GraphViz's neato tool. I wrote a Perl script to convert a directory structure to a diagram. The code's too cruel to be released to the world. You can imagine what it looks like by invoking:

neato -Txlib <<EOF
graph G {
  n1 [shape=folder width=1 style=filled label="baz" pos="0.00,0.00!"];
  n2 [shape=box height=.2 width=1 labelloc=t label="file" pos="0.00,-0.60!"];
  n3 [shape=folder width=1 style=filled label="foo" pos="0.00,-1.20!"];
  n4 [shape=folder width=1 style=filled label="bar" pos="1.20,-1.20!"];
  n3 -- n4;
  n1 -- n2 -- n3;
}
EOF

However, this output did not meet above criteria #3&4. It looked even cheaper than simple tree output.

The solution we settled for was dirtree.sty. It works like this: You download the dirtree.sty and dirtree.tex file, place them within your project and add a \usepackage{dirtree}. In theory, you can then include a \dirtree{} declaration (see the docs for details).

For example, this code (note the percent sign on line #1)...

\dirtree{ %
.1 .git/.
.2 HEAD.
.2 config.
.2 hooks/.
.2 index.
.2 info/.
.2 logs/.
.3 HEAD.
.3 refs/.
.2 objects/.
.3 info/.
.3 pack/.
.2 refs/.
.3 heads/.
.3 remotes/.
.3 tags/.
}

will produce the following graphic:

However, since it's not part of the LaTeX standard distribution, you cannot be sure about it's stability. It may use "dangerous" LaTeX constructs, etc... certainly nothing you want to include "as-is" in a book that'll eventually be printed. Also, the book will go through a conversion process to be distributed as an Ebook. You wouldn't want such a little LaTeX hack to be a show-stopper – or, worse yet, discover document corruption just after you got some thousand fresh copies from the printing press.

EPS/PDF files are stable, however. So what we did was this:

1. Put the \dirtree{} statements into separate files, including some \begin{document} stuff so that it will compile to a PDF file containing just the diagram.
2. Remove any whitespace. We use pdfcrop for that.
3. Convert to EPS.

In terms of Makefile statements, Valentin came up with this:

files=objektmodell-programm-crop\
    svn-stdlayout-crop\
    svn-nonstdlayout-crop\
    svn-branches-crop\
    git-branches-crop\
    git-dir-crop

pdfs=$(addsuffix .pdf, $(files))
epss=$(addsuffix .eps, $(files))

all: $(pdfs) $(epss)

clean:
    -rm -v *.pdf *.eps *.aux *.log

%.pdf : %.tex
    pdflatex $<

%-crop.pdf : %.pdf
    pdfcrop $<

%-crop.eps : %-crop.pdf
    pdftops -eps $< $@

Now it's as simple as make -C dir-listings && git add dir-listings (with an appropriate .gitignore file) to record changes to diagrams and recompile the PDF and EPS files. If you don't plan to keep the compiled files in your repository, you can also add a dependency for the subdirectory to your main Makefile.

Gestern frisch aus der Druckerei, jetzt hier: Heute sind meine Belegexemplare des Git-Buches angekommen! Damit ist es jetzt auch im Handel verfügbar.

Es ist ein wirklich tolles Gefühl, ein so großes Projekt abgeschlossen zu haben und das Ergebnis in den Händen zu halten. – Jetzt erst mal abwarten, wie so die Rückmeldungen ausfallen. ;-)

It has been a little more than three months since I last posted something here in my blog. Considering that the first post ever in this blog was from 1st of January this year, this pretty much looked like a "tried to blog, but gave it up again" thing.

I was really busy, however, and was simply not able to write a single post. What really ate up all my time was my latest pet project, writing a German book about Git. Valentin (my co-author) and I worked really hard throughout the past few weeks – only got up once in a while to get something to eat and stock up on Club Mate. The book is being published at Open Source Press and will be available from the end of June. Go buy it!

Now, with a lot of free time on my hands, I can finally get back to my studies (yes, really). Also, I will devote more time to this blog. :-)