Errata meines iX-Git-Artikels 12/2019

Dies sind die Errata

…zum Git-Artikel “Die vielfältigen Fähigkeiten von Git – Allerlei Süßes”, der im iX-Sonderheft “iX Developer, code(), build(), deploy(), moderne Softwareentwicklung” Winter 2019/20 erschienen ist.

Es handelte sich um eine fast textidentische Adaption eines Blogpost auf Heise Developer, der im Sommer (auf Wunsch der Redaktion) in zwei Teilen erschienen war: Teil 1 und Teil 2.

Es folgen zunächst einige allgemeine Bemerkungen zum Verhältnis von Autor und Redaktion sowie zum vorliegenden Fall. Weiter unten gibt es dann die eigentlichen Errata.

Die Redaktion

ist die Heldentruppe hinter den Veröffentlichungen, zu denen wir Autoren beitragen. Sie stehen an vorderster Front, sozusagen den Druckmaschinen direkt gegenüber. Ihr Lied wird selten gesungen. Ich persönlich habe die Mitglieder verschiedener Redaktionen durchaus als freundliche, zugewandte Menschen kennengelernt und arbeite gerne mit ihnen zusammen.

Allerdings ist die Zusammenarbeit nicht immer ungetrübt. Trübung und resultierender Ärger erwachsen m.E. aus drei Zutaten:

• Hektik
  Wenn unsereiner als Autor schon keine Zeit hat, so scheinen Redaktionen noch viel mehr in Stress und Hetze zu sein – Normalzustand. Das Ding wird lange nicht angefasst (weil die Ausgabe davor noch in Arbeit ist), und dann muss es ganz dringend schnell aus der Tür.

• Kleine Anpassungen
  Wenn ich als Autor meine, ich wäre fertig, fängt die Redaktion erst an. Sie glättet hier mal eine Formulierung, kürzt dort meinen Text, malt ein Bild neu, erfindet einen neuen Titel oder Untertitel und – je nach Blatt – fügt ein Aufmacherbild aus dem eigenen Fundus hinzu.

• Unverständnis
  Leider versteht die Redaktion nicht in jedem Fall, worum es in dem Artikel geht. Im Großen und Ganzen schon noch, aber leider weder im Detail noch in der Tiefe. Als Ergebnis kommt dann nicht selten heraus, was man auch beim besten Willen nur noch als “Verschlimmbesserung” bezeichnen kann.

Review!

Daher ist es wichtig (und glücklicherweise üblich), dass man als Autor die “fertige” Version des Artikels kurz vor Drucklegung noch einmal in die Finger kriegt. Das ist die Chance, das Schlimmste zu verhindern! Leider ist kurz vor Drucklegung häufig durchaus wörtlich zu nehmen: Man hat normalerweise keine Wochen, sondern nur wenige Tage Zeit, den Artikel zu prüfen – manchmal nur wenige Stunden.

Übrigens hat es sich bei den Redaktionen noch nicht herumgesprochen, wie segensreich das Programm diff ist. Statt dessen kriegt man den Artikel grundsätzlich in einem anderen Format zurück, als man ihn abgegeben hatte. Meist als PDF. Was wurde geändert? Ich persönlich will das genau wissen und vergleiche dann (leise schimpfend) das von mir Gelieferte und das nun “Fertige”: Wort für Wort, Satz für Satz.

Hier mal nicht. Leider.

So weit der normale Reviewvorgang, auf dem man als Autor bestehen kann und auch sollte. Aber im konkreten Fall ist der Reviewvorgang leider ausgefallen. Er war mir zunächst versprochen worden, dass ich den Artikel noch zu sehen bekomme. Das ist dann aber in Stress und Hektik untergegangen.

Nun gut: Shit happens. Der zuständige Redakteur hat sich entschuldigt und ich werde darüber hinwegkommen. Grundsätzlich bin ich ja stolz und freue mich darüber, dass mal wieder ein Artikel von mir in der iX erscheint.

Trotzdem möchte ich nicht kommentarlos geradestehen für Dinge, mit denen ich nicht einverstanden bin. Immerhin ist es mein Name, der über dem Artikel steht. Hier also öffentlich meine “Errata” (die ich liebend gerne rechtzeitig dem Redakteur nur privat mitgeteilt hätte).

Süßes oder saures?

Nebenbei bin ich ein sparsamer Konsument von Süßigkeiten. Wenn es nach mir geht, darf Zucker nur Teil einer Leckerei darstellen, was sowohl Menge als auch Geschmack betrifft. Alles andere läuft bei mir unter “knatschig süß”, das ist nicht so meins.

Fast alles von dem Süßkram, der im Heft als Illustration dient, finde ich denn auch eher eklig als verlockend. Meinen Artikel schmücken konkret mit buntem Zuckerzeug dekorierte glasierte Kirschen. Ich werfe normalerweise keine Lebensmittel weg, aber verirrten sich solche Kirschen auf meinen Teller, machte ich vermutlich eine Ausnahme. Obendrein finde ich, dass sich die Farbe der Kirschen mit der (vom Verlag geänderten) Farbe der Illustrationen unangenehm beißt.

Aber das ist noch nicht einmal gemeint. Es ist der Job der Redaktion, so ein Heft graphisch zu gestalten. Ich vertraue, dass man dort weiß, was man tut, und Grund zu der Annahme hat, dass Leute mit meinem Leckereien- und Farbgeschmack so selten sind, dass man sie getrost ignorieren kann.

Errata

Gleich die Einführung unnötig holprig

Mein ursprünglicher Text führt das Thema des Artikels ein wie folgt:

Wie ein roter Faden durchzieht “Vielfachheit” die Fähigkeiten, die der folgende Artikel vorstellt. Damit ist gemeint, dass von einem Repository aus “mehrere” verwalten werden können, wo im normalen Alltag meistens “eins” genügt.

Die Bezeichnungen “mehrere” und “eins” sind hier zunächst absichtlich offen gelassen. Was gemeint ist, wird anschließend erklärt. Damit man über das hier noch Fehlende nicht stolpert, sind beide in “” gesetzt. Die Redaktion hat die “” um “mehrere” leider weggelassen (komischerweise nicht die um “eins”).

Pfeil falschrum

Es folgt ein Bild eines typischen Retros mit Versionsgraph. In meinem Original war das ein normaler Git-Versionsgraph mit einem linearen master. Von dem zweigt ein Feature-Branch ab. Nach je einem Commit im master und im Feature-Branch folgt der Merge.

Da es nur ums Prinzip geht, begnüge ich mich hier mit einer Unicode-Skizze:

○ ← ○ ← ○ ← ○ ← ○
     ↖     ↙
        ○

Bei der Graphik im Heft wurde leider ein Pfeil verdreht. Es entsteht ein seltsamer Versionsgraph, den ich so noch nie gesehen habe:

○ ← ○ ← ○ ← ○ ← ○
     ↘     ↙
        ○

Jemand verknüpft da durch einen Merge Arbeit aus zwei Commits, aber diese Commits kommen aus demselben Branch, bedürfen also keines Merges. Wer macht so was? Und vor allem: Warum?

Aber vermutlich fragen diese Fragen zu kompliziert. Vermutlich hat einfach, wer die Graphik gemalt hat, keine eigenen Git-Kenntnisse und fand den Graph so ästhetisch ansprechender.

Schade.

“Ein Bild sagt mehr als tausend Worte,” heißt es. Dieser verdrehte Pfeil ist die Verschlimmbesserung meines Artikels, für die ich mich am meisten fremdschäme. Ich verleihe ihr hiermit feierlich die goldene Zitrone.

Denglish Plural

Im Englischen nutzt man “Repositories” als Plural von “Repository”. Im Deutschen heißt es aber “Repositorys”, analog zu “Hobbys” und “Partys”. Das war in meinem Text noch so, die Redaktion hat das verschlimmbessert und den “Denglish Plural” eingesetzt.

Formatierung von Branchnamen

Wie ich es ursprünglich geschrieben hatte, waren Git-Branches wie master durchgehend in Festbreitenschrift formatiert. Auf dem Weg zur Onlineausgabe des Artikels hat man das geändert, dort war master kursiv. Meinetwegen. Typographie ist etwas, wovon die Redaktion mehr Ahnung hat als ich.

Als ich den Text für die Papierausgabe zur Bearbeitung bekam, wurde mir bedeutet, dass ich mich um solche Formatierungen weder kümmern müsse noch könne. Ich erhielt unformatierten Text. Die Formatierungen würde die Redaktion nachpflegen.

Hat sie aber nicht: Branchnamen wie master sind jetzt überhaupt nicht mehr typographisch hervorgehoben (wie in diesem Satz beispielhaft demonstriert). Schade. Das glättet den Lesefluss nicht, sondern macht ihn holpriger.

Ungeschickte Absatzumbrüche

Ich hatte in meiner Version des Textes ziemlich oft neue Absätze angefangen. Die Redaktion hat mehrfach Dinge zu einem Absatz zusammengefügt, die bei mir getrennt waren. Das könnte man durchaus als Verbesserung sehen, wäre nicht oft recht ungeschickt zusammengefügt worden.

Ich fange ein neues Thema an, mein Absatzumbruch wird weggelassen. Anschließend kommen Details zum neuen Thema: Die bleiben als eigener Absatz abgetrennt. Es wird also von zwei Absatzumbrüchen der erste, wichtigere weggelassen und der zweite, nicht so wichtige bleibt erhalten. Beispiele: Ich wechsle von der Besprechung von git stash zu der von git worktree: Der Absatzneuanfang dazwischen fehlt. Oder ich wechsle von der Nutzung mehrerer Worktrees auf die interne Organisation: Wieder hängt in einem Absatz zusammen, was nicht zusammen gehört. Auch, wo ich einführe, dass man mit einem neuen Worktree gleich einen neuen Branch anlegen kann, hätte ich meinen Absatzneuanfang gerne erhalten gesehen.

Commits, Branches, Remotes usw.

werden von verschiedenen Worktrees desselben Repos geteilt. Hinter dem “usw.” verbergen sich hier zum Beispiel Tags oder auch repositoryspezifische Konfigurationen. Die Redaktion hat das “usw.” weggelassen. Das macht die Aussage nicht falsch, ist aber auch keine Verbesserung.

“Den Autor”

In einem Blogpost geht das inzwischen, aber wenn es um einen auf Papier gedruckten Artikel geht, genieren sich die Redaktionen noch, ein schlichtes “ich” zu erlauben oder stehen zu lassen.

Meine Formulierung war:

Vielmehr baten mich die Firmenadmins meines damaligen Arbeitgebers, eine pragmatische Einzelfalllösung abseits der offiziellen Infrastruktur zu finden.

Im Heft stand dann:

Vielmehr baten die Firmenadmins des damaligen Arbeitgebers den Autoren, eine pragmatische Einzelfalllösung abseits der offiziellen Infrastruktur zu finden.

Kann man an sich machen. Aber im Detail: Autsch. Richtig wäre schlicht “den Autor”.

Weggelassene Verzeichnisse

führen dazu, dass im Heft abgedruckten Kommandozeilenbeispiele nicht funktionieren. Aus dem korrekten

git remote add collab user@server.example.org:collab-repo

wurde das unvollständige und so nicht funktionierende

git remote add collab user@server.example.org

und aus dem korrekten

git clone user@server.example.org:collab-repo

wurde das ebenfalls unvollständige und falsche

git clone user@server.example.org

Sehr ärgerlich, das! Nicht-funktionierende Codebeispiele finde ich besonders blamabel. Weil aber nicht jeder diesen Code ausführen wird, schrammt dieses Problem am ersten Platz vorbei. Es erhält von mir knapp nur die silberne Zitrone für die aus meiner Sicht zweitschlimmste Verschlimmbesserung.

Aus Inline wird Listing

Etwas später ist ein mehrzeiliges CLI-Beispiel in einen “Kasten” ausgegliedert worden. So etwas muss man manchmal machen, klar. Der angepasste Text heißt dann aber:

Dann kann A das Repository wie in Listing 1 initialisieren:

Da hätte man den “:” gleich mit anpassen sollen, also durch einen “.” ersetzen.

Ganz am Ende des Artikels wurden ebenfalls ein paar Zeilen Shellskript aus dem Text ausgegliedert; es entstand Listing 3. Die Redaktion kam auf den Titel “Ein Skript zum Erzeugen des Outputs”. Da hätte ich gerne eine Chance gehabt, mir für dieses Listing einen sinnvollen, passenden Titel auszudenken.

Und nochmal Denglish

Meine Formulierung war:

Als “Author” wird in der Git-Terminologie die Person bezeichnet, …

Zumindest ich finde, dieser deutsche Satz wird sofort holpriger zu lesen, wenn man, wie geschehen, die “” um das englische Wort weglässt.

Kürzungen beim HTTPS-Creds

Ziemlich am Ende des Artikels gibt es die Befehlszeile:

git config --global credential.https://git.example.org.helper /usr/local/↩
                                                              bin/gitcreds

Die setzt voraus, dass das vorher besprochende Skript als /usr/local/bin/gitcreds zur Verfügung steht. So hatte ich es auch beschrieben. Aber für die Papierversion wurde hier Text weggelassen und dabei fiel auch die Pfadangabe weg. Das macht die Befehlszeile unklarer und etwas verwirrend.

Noch wichtiger: Der Artikel reißt hier nur an, wie es geht. Für nähere Information wurde auf die passende Stelle der Git-Dokumentation verwiesen, “Credential Helpers” in “API-Credentials”. Diesen Verweis hat die Redaktion leider ebenfalls gestrichen.

Schade. Die passende Stelle in der Git-Doku ist leider gar nicht so leicht zu finden, wenn man nicht schon weiß, dass es sie gibt. Diesen beiden Kürzungen aus dem Material, wie man git HTTPS-Credentials zur Verfügung stellt, verleihe ich daher gemeinsam die bronzene Zitrone der dritt-unangenehmsten Änderung an meinem Artikel.