Kapitel 5. Verteiltes Git

Git unterstützt mehrere Protokolle, um auf ein Remote-Repository zuzugreifen, die gängigsten drei sind das Git-Protokoll, SSH und HTTP(S). Das Git-Protokoll wurde speziell für Git entwickelt und begünstigt die Datenübertragung, da immer die kleinstmögliche Datenmenge übertragen wird. Es unterstützt keine Authentifizierung und wird daher häufig in einer SSH-Verbindung übertragen. Dadurch wird sowohl eine effiziente (Git-Protokoll) als auch sichere (SSH) Übertragung gewährleistet. HTTP(S) kommt dann zum Einsatz, wenn eine Firewall sehr restriktiv konfiguriert ist und die zugelassenen Ports drastisch eingeschränkt sind.^[67]

Im Allgemeinen enthält eine valide URL das Übertragungsprotokoll, die Adresse des Servers sowie den Pfad zu dem Repository:^[68]

Für das SSH-Protokoll existiert noch die Kurzform:

Außerdem ist es möglich, lokale Repositories mit der folgenden Syntax zu klonen:

Wenn Sie wissen wollen, welche URLs für ein Remote-Repository konfiguriert sind, verwenden Sie die Option --verbose bzw. -v von git remote:

$ git remote -v
origin  git://github.com/esc/git-cheatsheet-de.git (fetch)
origin  git://github.com/esc/git-cheatsheet-de.git (push)

Sie sehen, dass es zwei URLs für das Remote-Repository origin gibt, die aber standardmäßig auf denselben Wert gesetzt sind. Die erste URL (fetch) gibt an, von wo und mit welchem Protokoll Veränderungen heruntergeladen werden. Die zweite URL (push) gibt an, wohin und mit welchem Protokoll Veränderungen hochgeladen werden. Unterschiedliche URLs sind vor allem dann interessant, wenn Sie mit verschiedenen Protokollen herunter- bzw. hochladen. Ein gängiges Beispiel ist, mit dem Git-Protokoll (git://) herunterzuladen und mit dem SSH-Protokoll (ssh://) hoch. Es wird dann ohne Authentifizierung und Verschlüsselung heruntergeladen, was einen Geschwindigkeitsvorteil bietet, aber mit Authentifizierung und Verschlüsselung hochgeladen, was sicherstellt, dass nur Sie oder andere zugriffsberechtigte Personen hochladen können. Mit dem Kommando git remote set-url passen Sie die URLs an:

$ git remote set-url --add \
  --push origin git@github.com:esc/git-cheatsheet-de.git
$ git remote -v
origin  git://github.com/esc/git-cheatsheet-de.git (fetch)
origin  git@github.com:esc/git-cheatsheet-de.git (push)

Der aktuelle Zustand des Remote-Repositorys wird lokal gespeichert. Git verwendet dazu den Mechanismus der Remote-Tracking-Branches, spezielle Branches – also lokale Referenzen – , die den Zustand der Branches im Remote, sog. Remote-Branches, widerspiegeln. Sie „verfolgen“ also die Remote-Branches und werden bei einer Synchronisation mit dem Remote entsprechend von Git vorgerückt bzw. gesetzt, sofern sich die Branches in dem Remote verändert haben. Im Hinblick auf den Commit-Graphen sind Remote-Tracking-Branches Markierungen innerhalb des Graphen, die auf die gleichen Commits zeigen wie die Branches im Remote-Repository. Sie können Remote-Tracking-Branches nicht wie normale Branches verändern, Git verwaltet sie automatisch, sorgt also für deren Aktualisierung. Wenn Sie ein Repository klonen, initialisiert Git für jeden Remote-Branch einen Remote-Tracking-Branch.

Abbildung 5.2. Erzeugte Remote-Tracking-Branches

In Abbildung 5.2, „Erzeugte Remote-Tracking-Branches“ sehen Sie ein Beispiel. Das Remote-Repository origin hat drei Branches: pu, maint und master. Git erstellt in dem geklonten Repository für jeden dieser Remote-Branches einen Remote-Tracking-Branch. Außerdem wird in dem Klon ein lokaler Branch master erstellt, der dem Remote-Branch master entspricht. Dieser wird ausgecheckt und ist der Branch, in dem Sie arbeiten sollten, wenn Sie vorhaben, Commits in den master hochzuladen (siehe aber auch Abschnitt 5.3.1, „git fetch“).

In dem Beispiel mit dem Git-Spickzettel gibt es auf der Remote-Seite nur einen einzigen Branch, nämlich master. Darum erzeugt Git in dem Klon auch nur einen Remote-Tracking-Branch, und zwar origin/master. Der Befehl git branch -r zeigt alle Remote-Tracking-Branches an:

$ git branch -r
  origin/HEAD -> origin/master
  origin/master

Der Sondereintrag origin/HEAD -> origin/master besagt, dass in dem Remote-Repository der HEAD auf den Branch master zeigt. Das ist für das Klonen insofern wichtig, als dieser Branch nach dem Klonen ausgecheckt wird. Die Liste der Remote-Tracking-Branches ist in dem Beispiel etwas spärlich, mehr Einträge sehen Sie in einem Klon des Git-via-Git Repositorys:

$ git branch -r
  origin/HEAD -> origin/master
  origin/html
  origin/maint
  origin/man
  origin/master
  origin/next
  origin/pu
  origin/todo

Alle Branches lassen Sie sich mit git branch -a anzeigen:

$ git branch -a
* master
  remotes/origin/HEAD -> origin/master
  remotes/origin/master

In diesem Fall verwendet Git das Präfix remotes/, um Remote-Tracking-Branches eindeutig von den normalen zu unterscheiden. Haben Sie die Farbausgabe aktiviert, werden die unterschiedlichen Branches zudem farblich kodiert: der ausgecheckte Branch grün, Remote-Tracking-Branches rot.

Remote-Tracking-Branches sind auch nur Referenzen und werden daher wie alle Referenzen unter .git/refs gespeichert. Da es sich aber um besondere Referenzen handelt, die zudem noch mit einem Remote-Repository verknüpft sind, landen sie unter .git/refs/remotes/<remote-name> (siehe auch Abschnitt 3.1.1, „HEAD und andere symbolische Referenzen“). In Gitk werden die Remote-Tracking-Branches mit dem Präfix remotes/<remote-name>/ angezeigt, das zudem dunkelgelb gefärbt ist (Abbildung 5.3, „Branch next und der entsprechende Remote-Tracking-Branch in Gitk“).

Abbildung 5.3. Branch next und der entsprechende Remote-Tracking-Branch in Gitk

Sobald in einem Remote neue Commits von anderen Entwicklern angelegt wurden, wollen Sie diese in Ihr lokales Repository herunterladen. Im einfachsten Fall wollen Sie nur herausfinden, welche Commits Sie lokal noch nicht haben, diese herunterladen und die Remote-Tracking-Branches auf den neuesten Stand bringen, so dass sie den aktuellen Zustand im Remote widerspiegeln.

Verwenden Sie dazu das Kommando git fetch:

$ git fetch origin
...
From github.com:esc/git-cheatsheet-de
   79170e8..003e3c7  master     -> origin/master

Git quittiert den Aufruf mit einer Meldung, dass origin/master von dem Commit 79170e8 auf den Commit 003e3c7 gesetzt wurde. Die Notation master -> origin/master besagt, dass der Branch master aus dem Remote verwendet wurde, um den Remote-Tracking-Branch origin/master zu aktualisieren. Sprich: Branches aus dem Remote auf der linken Seite und Remote-Tracking-Branches auf der rechten.

Welche Auswirkung das auf den Commit-Graphen hat, sehen Sie in Abbildung 5.4, „Remote-Tracking-Branches werden aktualisiert“: Auf der linken Seite ist der Ausgangszustand des Remote origin und daneben der des Klons dargestellt. Sowohl im Remote als auch im Klon sind seit der letzten Synchronisation neue Commits hinzugekommen (C und D). Der Remote-Tracking-Branch origin/master im Klon zeigt auf Commit B; dies ist der letzte Zustand des Remotes, der dem Klon bekannt ist. Durch einen Aufruf von git fetch origin aktualisiert Git den Remote-Tracking-Branch im Klon, damit dieser den aktuellen Zustand des master (zeigt auf Commit C) im Remote widerspiegelt. Dazu lädt Git den fehlenden Commit C herunter und setzt anschließend den Remote-Tracking-Branch darauf.

Abbildung 5.4. Remote-Tracking-Branches werden aktualisiert

[remote "origin"]
    fetch = +refs/heads/*:refs/remotes/origin/*
    url = git://github.com/esc/git-cheatsheet-de.git

 + f5225b8..0efec48 pu         -> origin/pu  (forced update)

[remote "firma"]
    url = axel@example.com:produkt.git
    fetch = +refs/heads/master:refs/remotes/origin/master
    fetch = +refs/heads/beatrice/*:refs/remotes/origin/beatrice/*
    fetch = +refs/heads/carlos/*:refs/remotes/origin/carlos/*

$ git fetch origin +refs/heads/master:refs/remotes/origin/master

$ git fetch origin master
From github.com:esc/git-cheatsheet-de
 * branch            master     -> FETCH_HEAD
$ cat .git/FETCH_HEAD
003e3c70ce7310f6d6836748f45284383480d40e
    branch 'master' of github.com:esc/git-cheatsheet-de
$ git merge FETCH_HEAD

$ git remote prune origin

$ git fetch --prune

$ git checkout -b next origin/next
Branch next set up to track remote branch next from origin.
Switched to a new branch next

$ git checkout next
Branch next set up to track remote branch next from origin.
Switched to a new branch next

Angenommen, Sie wollen Commits aus dem Remote-Repository in Ihren lokalen Branch übernehmen. Dazu führen Sie zuerst ein git fetch aus, um neue Commits zu holen, und anschließend mergen Sie die Veränderung aus dem entsprechenden Remote-Tracking-Branch:^[71]

$ git merge origin/master
Updating 79170e8..003e3c7
Fast-forward
 cheatsheet.pdf |  Bin 89792 -> 95619 bytes
 cheatsheet.tex |   19 +++++++++++++++++---
 2 files changed, 16 insertions(+), 3 deletions(-)

Für diesen Anwendungsfall stellt Git das Kommando git pull bereit, um Ihren Workflow zu beschleunigen. Es ist eine Kombination von git fetch und git merge oder git rebase.

Neue Commits von origin herunterladen und alle Commits, die vom dortigen master referenziert werden, in den aktuellen Branch mergen ist also mit folgendem Kommando zu erledigen:

$ git pull origin master
...
From github.com:esc/git-cheatsheet-de
   79170e8..003e3c7  master     -> origin/master
Updating 79170e8..003e3c7
Fast-forward
 cheatsheet.pdf |  Bin 89792 -> 95619 bytes
 cheatsheet.tex |   19 ++++++++++++++++---
 2 files changed, 16 insertions(+), 3 deletions(-)

In Abbildung 5.5, „Was bei einem Pull passiert“ illustrieren wir den Vorgang. Auf der linken Seite sehen Sie das Remote-Repository origin und daneben den aktuellen Zustand des lokalen Repositorys. Das Repository wurde geklont, als es nur die Commits A und B enthielt, daher zeigt der Remote-Tracking-Branch origin/master auf B. Mittlerweile sind sowohl im Remote (C) als auch im lokalen Repository (D) Commits hinzugekommen.

Auf der rechten Seite ist der Zustand nach git pull origin master abgebildet. Commit C wurde ins lokale Repository übernommen. Der im pull enthaltene fetch-Aufruf hat den Remote-Tracking-Branch aktualisiert, d.h. er zeigt auf denselben Commit wie der master in origin und spiegelt somit den dortigen Zustand wider. Außerdem hat der im pull enthaltene merge-Aufruf den master aus origin in den lokalen master integriert, was Sie an dem Merge-Commit M sowie der aktuellen Position des lokalen master erkennen.

Abbildung 5.5. Was bei einem Pull passiert

Alternativ weist die Option --rebase das Pull-Kommando an, nach dem fetch den lokalen Branch per Rebase auf den Remote-Tracking-Branch aufzubauen:

$ git pull --rebase  origin master

In Abbildung 5.6, „Was bei einem Pull mit Rebase passiert“ sehen Sie, was passiert, wenn Sie statt des Standard-Merge einen Rebase ausführen.

Abbildung 5.6. Was bei einem Pull mit Rebase passiert

Die Ausgangssituation ist dieselbe wie in Abbildung 5.5, „Was bei einem Pull passiert“. Der im pull enthaltene fetch rückt den Remote-Tracking-Branch origin/master auf den Commit C. Der rebase erzeugt jedoch keinen Merge-Commit; stattdessen erhält der Commit D durch einen Aufruf von rebase eine neue Basis, und der lokale master wird auf den neuen Commit D' gesetzt. (Rebase wird ausführlich in Abschnitt 4.1, „Commits verschieben – Rebase“ beschrieben.)

[branch "master"]
    remote = origin
    merge = refs/heads/master

$ git fetch
...
From github.com:esc/git-cheatsheet-de
   79170e8..003e3c7  master     -> origin/master
$ git pull
...
From github.com:esc/git-cheatsheet-de
   79170e8..003e3c7  master     -> origin/master
Updating 79170e8..003e3c7
Fast-forward
 cheatsheet.pdf |  Bin 89792 -> 95619 bytes
 cheatsheet.tex |   19 ++++++++++++++++---
 2 files changed, 16 insertions(+), 3 deletions(-)

$ git fetch
fatal: No remote repository specified.  Please, specify either a URL or
a remote name from which new revisions should be fetched.

$ git config branch.master.rebase true

Git-Anfängern stellt sich häufig die Frage, ob sie nun fetch oder pull verwenden sollen. Die Antwort hängt davon ab, wie entwickelt wird: Wie groß ist das Projekt? Wie viele Remotes gibt es? Wie stark werden Branches eingesetzt?

# Repository Klonen
$ git clone <URL>
# Arbeiten und lokale Commits machen
$ git add ...
$ git commit
# Veränderungen von Anderen herunterladen
$ git pull
# Eigene Veränderungen hochladen
$ git push
# Weiter arbeiten, und Synchronisation bei Bedarf wiederholen
$ git commit

# Veränderungen von Anderen herunterladen
$ git remote update
...
   79170e8..003e3c7  master     -> origin/master

# Den Status der Remote-Tracking-Branches abfragen
$ git branch -vv
* master 79170e8 [origin/master: behind 1] Lizenz hinzugefügt

# Veränderungen einsehen
$ git log -p ..@{u}

# Heruntergeladene Änderungen übernehmen
$ git merge @{u}
Updating 79170e8..003e3c7
Fast-forward
...

# ... oder eigene Änderungen darauf neu aufbauen
$ git rebase @{u}

# Änderungen dann hochladen
$ git push

$ git config --global alias.fft "merge --ff-only @{u}"

Es gibt zwei Möglichkeiten, um Referenzen im Remote wieder zu löschen: Die ältere (vor Git Version 1.7.0) ist, beim Refspec die lokale Referenz wegzulassen – diese Anweisung bedeutet, Sie möchten „nichts“ hochladen. Sie ersetzen also eine existierende durch die leere Referenz.

$ git push origin :bugfix

In neueren Git-Versionen wird aber in der Regel das Kommando git push mit der Option --delete verwendet, was syntaktisch viel deutlicher ist:

$ git push origin --delete bugfix

Beachten Sie, dass in anderen Klonen der ggf. vorhandene Remote-Tracking-Branch origin/bugfix dadurch nicht automatisch verschwindet! Siehe dafür den Abschnitt über Pruning weiter oben (Abschnitt 5.3, „Commits herunterladen“).

Im Alltag führen Sie git push oft ohne Angabe von Remote und Refspec aus. In dem Fall entscheidet Git anhand der Konfigurationseinträge (Upstream-Branch und push.default), welche Referenzen wohin geschickt werden.

$ git push
...
To git@github.com:esc/git-cheatsheet-de.git
   79170e8..003e3c7  master -> master

Git geht standardmäßig so vor:^[73] Wenn Sie kein Remote angeben, dann sucht Git die Upstream-Konfiguration des aktuellen Branches heraus. Sofern der Name des Branches auf der Remote-Seite mit dem Namen des lokalen Branches übereinstimmt, wird die entsprechende Referenz hochgeladen (dies soll Sie davor schützen, bei fehlerhafter Upstream-Konfiguration zum Beispiel Ihren Branch devel nach master hochzuladen). Ist kein Upstream-Branch konfiguriert, bricht Git mit einer Fehlermeldung ab:

$ git push
fatal: The current branch master has no upstream branch.
To push the current branch and set the remote as upstream, use

    git push --set-upstream origin master

Wenn Sie mit git push <remote> zwar ein Remote, aber keinen Branch angeben, so versucht Git, den aktuellen Branch unter dem gleichen Namen in das Remote hochzuladen.

Die hier beschriebene Strategie wird auch als simple bezeichnet. Sie tut für die meisten Anwendungsfälle das, was der Nutzer erwartet, und schützt vor vermeidbaren Fehlern. Die dafür zuständige Option push.default können Sie aber bei Bedarf auch auf einen der folgenden Werte setzen:

Git nimmt die Konfiguration von Upstream-Branches in einigen Fällen automatisch vor (zum Beispiel nach einem git clone). Insbesondere für neue Branches, die Sie das erste Mal hochladen, müssen Sie dies allerdings explizit tun. Sie können dafür entweder im Nachhinein die Option --set-upstream-to oder kurz -u von git branch verwenden:

$ git push origin new-feature
$ git branch -u origin/new-feature
Branch new-feature set up to track remote branch new-feature from origin.

Alternativ und wenn Sie daran denken, können Sie aber auch gleich beim Aufruf von git push mit der Option -u die Konfiguration schreiben lassen:

$ git push -u origin new-feature

Um die Upstream-Konfiguration Ihrer Branches anzuzeigen, rufen Sie git branch -vv auf. In der Ausgabe wird (falls vorhanden) der Upstream-Partner eines Branches in eckigen Klammern angezeigt.

Das Kommando git remote show gibt eine prägnante Zusammenfassung des Remotes, inklusive den dort verfügbaren Branches, ob diese lokal verfolgt werden (Tracking-Status) und welche lokalen Branches für bestimmte Aufgaben konfiguriert sind.

Das Kommando muss beim Remote den aktuellen Stand erfragen, d.h. der Befehl scheitert, wenn das Remote nicht verfügbar ist, z.B. aufgrund fehlender Netzwerkverbindung. Die Option -n unterbindet die Abfrage.

$ git remote show origin
* remote origin
  Fetch URL: git://git.kernel.org/pub/scm/git/git.git
  Push  URL: git://git.kernel.org/pub/scm/git/git.git
  HEAD branch: master
  Remote branches:
    html   tracked
    maint  tracked
    man    tracked
    master tracked
    next   tracked
    pu     tracked
    todo   tracked
  Local branches configured for 'git pull':
    master merges with remote master
    pu     merges with remote pu
  Local refs configured for 'git push':
    master pushes to master (local out of date)
    pu     pushes to pu     (up to date)

Haben Sie einen Upstream-Branch konfiguriert, erhalten Sie beim Wechseln des Branches (git checkout) und Abfragen des Status (git status) eine Benachrichtigung über den Zustand des Branches im Vergleich mit dem Upstream, z.B.:

$ git checkout master
Your branch is behind 'origin/master' by 73 commits, and can be
fast-forwarded.

Hier gibt es vier verschiedene Möglichkeiten:

Mit der Option -v (nur den Vergleich) oder -vv (Vergleich und Upstream-Bezeichnung) zeigt git branch die entsprechenden Informationen für lokale Branches:

$ git branch -vv
* master      0a464e9 [origin/master: ahead 1] docs: fix grammar in
git-tags.txt
  feature     cd3065f Merge branch 'kc/gitweb-pathinfo-w-anchor'
  next        be8b495 [origin/next] Merge branch master into next
  pu          0c0c536 [origin/pu: behind 3] Merge branch
'jk/maint-merge-rename-create' into pu

Das Kommando gibt für alle Branches das SHA-1-Präfix sowie die Commit-Message des aktuellen Commits aus. Ist für den Branch ein Upstream konfiguriert, liefert Git sowohl den Namen als auch einen Vergleich zum Upstream. In dem Beispiel sehen Sie vier verschiedene Branches. master hat einen zusätzlichen Commit, der noch nicht ins Remote hochgeladen wurde, und ist daher ahead. Der Branch feature wiederum hat keinen Upstream-Branch konfiguriert, ergo: er existiert momentan nur lokal. Der Branch next ist auf demselben Stand wie der entsprechende Remote-Tracking-Branch (up-to-date). Der Branch pu andererseits „hinkt“ seinem Upstream hinterher und wird daher als behind angezeigt. Der einzige Zustand, der hier fehlt, ist diverged – dann werden sowohl ahead als auch behind inklusive der Anzahl der „fehlenden“ Commits angezeigt.

Um einen Pull-Request automatisch zu generieren, gibt es das Git-Kommando request-pull. Die Syntax lautet:

git request-pull <Anfang> <URL> [<Ende>]

Als <URL> geben Sie Ihr öffentliches Repository an (entweder als tatsächliche URL oder als konfiguriertes Remote-Repository), und als <Anfang> wählen Sie die Referenz, auf die das Feature aufbaut (in vielen Fällen den Branch master, der mit dem Master-Branch des offiziellen Repositorys übereinstimmen sollte). Optional können Sie ein <Ende> angeben; lassen Sie diese Angabe weg, so verwendet Git HEAD.

Die Ausgabe erfolgt nach Standard-Out und enthält die URL sowie den Branch-Namen des Repositorys, die Kurzbeschreibung aller Commits nach Autor sowie ein Diff-Stat, also eine Bilanz von hinzugekommenen und gelöschten Zeilen nach Dateien. Diese Ausgabe lässt sich bequem an ein E-Mail-Programm weiterleiten. Fügen Sie noch die Option -p hinzu, wird unter den Text noch ein Patch mit allen Änderungen angehängt.

Zum Beispiel um jemanden darum zu bitten, die zwei neuesten Commits aus einem Repository herunterzuladen:

$ git request-pull HEAD~2 origin
The following changes since commit d2640ac6a1a552781[...]c48e08e695d53:

  README verbessert (2010-11-20 21:27:20 0100)

are available in the git repository at:
  git@github.com:esc/git-cheatsheet-de.git master

Valentin Haenel (2):
      Lizenz hinzugefügt
      URL hinzugefügt und Metadaten neu formatiert

 cheatsheet.pdf |  Bin 89513 -> 95619 bytes
 cheatsheet.tex |   18 ++++++++++++++++--
 2 files changed, 16 insertions(), 2 deletions(-)

Prinzipiell lädt Git neue Tags automatisch bei einem Aufruf von git fetch bzw. git pull herunter. Das heißt, wenn Sie einen Commit herunterladen, auf den ein Tag zeigt, so wird dieses Tag mitgeliefert. Schließen Sie jedoch mit einem Refspec einzelne Branches aus, so werden Commits in diesen Branches nicht heruntergeladen – und somit auch keine Tags, die evtl. auf diese Commits zeigen. Fazit: Git lädt nur relevante Tags herunter. Mit den Optionen --no-tags (keine Tags) und --tags bzw. -t (alle Tags) passen Sie das Standardverhalten an. Beachten Sie aber, dass Sie mit --tags nicht nur die Tags herunterladen, sondern notwendigerweise auch die Commits, auf die die Tags zeigen.

Git benachrichtigt Sie, wenn neue Tags eintreffen:

$ git fetch
[fetch output]
From git://git.kernel.org/pub/scm/git/git
 * [new tag]         v1.7.4.2   -> v1.7.4.2

Wenn Sie wissen wollen, welche Tags auf der Remote-Seite vorhanden sind, verwenden Sie git ls-remote mit der Option --tags. Zum Beispiel erhalten Sie alle Release-Candidates der Git-Version 1.7.1 mit folgendem Aufruf:

$ git ls-remote origin --tags v1.7.1-rc*
bdf533f9b47dc58ac452a4cc92c81dc0b2f5304f    refs/tags/v1.7.1-rc0
537f6c7fb40257776a513128043112ea43b5cdb8    refs/tags/v1.7.1-rc0^{}
d34cb027c31d8a80c5dbbf74272ecd07001952e6    refs/tags/v1.7.1-rc1
b9aa901856cee7ad16737343f6a372bb37871258    refs/tags/v1.7.1-rc1^{}
03c5bd5315930d8d88d0c6b521e998041a13bb26    refs/tags/v1.7.1-rc2
5469e2dab133a197dc2ca2fa47eb9e846ac19b66    refs/tags/v1.7.1-rc2^{}

Git gibt die SHA-1-Summen der Tags und deren Inhalt^[75] aus.

Git lädt Tags nicht automatisch hoch. Sie müssen diese, ähnlich den Branches, explizit an git push übergeben, z.B. um das Tag v0.1 hochzuladen:

$ git push origin v0.1

Wenn Sie gleich alle Tags hochladen wollen, verwenden Sie die Option --tags. Aber Vorsicht: Vermeiden Sie diese Option, wenn Sie, wie in Abschnitt 3.1.3, „Tags – Wichtige Versionen markieren“ beschrieben, Annotated Tags zur Kennzeichnung von Versionen verwenden und Lightweight Tags, um lokal etwas zu markieren. Denn mit der Option würden Sie, wie schon gesagt, alle Tags hochladen.

Achtung: Wenn Sie ein Tag einmal hochgeladen haben, sollten Sie es auf keinen Fall verändern! Der Grund: Angenommen, Axel verändert ein Tag, etwa v0.7, das er bereits veröffentlicht hat. Zunächst zeigte es auf den Commit 5b6eef und nun auf bab18e. Beatrice hatte bereits die erste Version, die auf 5b6eef zeigt, heruntergeladen, Carlos aber noch nicht. Beim nächsten Mal, wenn Beatrice git pull aufruft, lädt Git nicht die neue Version von dem Tag v0.7 herunter; die Annahme ist, dass sich Tags nicht verändern, und darum überprüft Git die Gültigkeit des Tags nicht! Führt Carlos nun git pull aus, erhält er auch das Tag v0.7, das aber jetzt auf bab18e zeigt. Zuletzt sind zwei Versionen des Tags – die jeweils auf unterschiedliche Commits zeigen – im Umlauf. Keine besonders hilfreiche Situation. Wirklich verwirrend wird es, wenn sowohl Carlos als auch Beatrice dasselbe, öffentliche Repository verwenden und standardmäßig alle Tags hochladen.^[76] Das Tag „springt“ quasi im öffentlichen Repository zwischen zwei Commits hin und her; welche Version Sie mit einem Klon erhalten, hängt davon ab, wer zuletzt gepusht hat.

Sollte Ihnen dieses Missgeschick doch einmal passieren, haben Sie zwei Möglichkeiten:

Das Kommando git format-patch exportiert einen oder mehrere Commits als Patches im Unix-Mailbox-Format und gibt pro Commit eine Datei aus. Die Dateinamen bestehen aus einer sequenziellen Nummerierung und der Commit-Message und enden auf .patch.^[77] Als Argument erwartet das Kommando entweder einen einzelnen Commit oder eine Auswahl wie z.B. A..B. Geben Sie einen einzelnen Commit an, wertet Git dies als die Auswahl von dem Commit bis zum HEAD.

Abbildung 5.9. Drei Commits nach master als Patches formatieren

Abbildung 5.9, „Drei Commits nach master als Patches formatieren“ zeigt die Ausgangssituation. Wir wollen die drei Commits in dem Branch fix-git-svn-docs, also alle Commits ab master, als Patches exportieren:

$ git format-patch master
0001-git-svn.txt-fix-usage-of-add-author-from.patch
0002-git-svn.txt-move-option-descriptions.patch
0003-git-svn.txt-small-typeface-improvements.patch

$ git format-patch -1
0001-git-svn.txt-small-typeface-improvements.patch

$ git format-patch -1 9126ce7
0001-git-svn.txt-fix-usage-of-add-author-from.patch

Die generierten Dateien enthalten unter anderem die Header-Felder From, Date und Subject, die zum Verschicken als E-Mail dienen. Diese Felder werden anhand der im Commit vorhandenen Information – Autor, Datum und Commit-Message – vervollständigt. Des weiteren enthalten die Dateien eine Diff-Stat-Zusammenfassung sowie die Veränderungen selbst als Patch im Unified-Diff-Format. Den Zusatz [PATCH m/n]^[78] in der Betreff-Zeile nutzt Git später, um die Patches in der richtigen Reihenfolge anzuwenden.

Es folgt ein entsprechender Ausschnitt:

$ cat 0003-git-svn.txt-small-typeface-improvements.patch
From 6cf93e4dae1e5146242338b1b9297e6d2d8a08f4 Mon Sep 17 00:00:00 2001
From: Valentin Haenel <valentin.haenel@gmx.de>
Date: Fri, 22 Apr 2011 18:18:55 0200
Subject: [PATCH 3/3] git-svn.txt: small typeface improvements

Signed-off-by: Valentin Haenel <valentin.haenel@gmx.de>
Acked-by: Eric Wong <normalperson@yhbt.net>
---
 Documentation/git-svn.txt |    8 ++++----
 1 files changed, 4 insertions(), 4 deletions(-)

diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
...

Wenn Sie vorhaben, eine Serie von Patches zu verschicken, ist es empfehlenswert, mit der Option --cover-letter eine Art „Deckblatt“ zu erzeugen, in dem Sie die Serie beschreiben. Die Datei heißt standardmäßig 0000-cover-letter.patch. Abgesehen von den Standard-Headern, sieht eine solche Datei wie folgt aus:

Subject: [PATCH 0/3] *** SUBJECT HERE ***

*** BLURB HERE ***

Valentin Haenel (3):
  git-svn.txt: fix usage of --add-author-from
  git-svn.txt: move option descriptions
  git-svn.txt: small typeface improvements

 Documentation/git-svn.txt |   22 +++++++++++-----------
 1 files changed, 11 insertions(+), 11 deletions(-)

Wie Sie sehen, ist im Subject: noch das Präfix [PATCH 0/3] eingetragen; so sehen alle Empfänger sofort, dass es sich um ein Deckblatt handelt. Außerdem enthält die Datei die Ausgabe von git shortlog sowie git diff --stat. Ersetzen Sie *** SUBJECT HERE *** durch einen Betreff und *** BLURB HERE *** durch eine Zusammenfassung der Patch-Serie. Verschicken Sie die Datei zusammen mit den Patch-Dateien.

Versenden Sie die generierten Dateien mit git send-email (oder einem E-Mail-Client Ihrer Wahl). Das Kommando erwartet als einziges zwingendes Argument entweder eine oder mehrere Patch-Dateien, ein Verzeichnis voller Patches oder aber eine Auswahl von Commits (in dem Fall ruft Git zusätzlich intern git format-patch auf):

$ git send-email 000*
0000-cover-letter.patch
0001-git-svn.txt-fix-usage-of-add-author-from.patch
0002-git-svn.txt-move-option-descriptions.patch
0003-git-svn.txt-small-typeface-improvements.patch
Who should the emails appear to be from? [Valentin Haenel
<valentin.haenel@gmx.de>]

$ git send-email master
/tmp/HMSotqIfnB/0001-git-svn.txt-fix-usage-of-add-author-from.patch
/tmp/HMSotqIfnB/0002-git-svn.txt-move-option-descriptions.patch
/tmp/HMSotqIfnB/0003-git-svn.txt-small-typeface-improvements.patch
Who should the emails appear to be from? [Valentin Haenel
<valentin.haenel@gmx.de>]

Das Kommando git send-email setzt die Felder Message-Id sowie In-Reply-To. Damit sehen alle E-Mails nach der ersten wie Antworten auf diese aus und werden dadurch von den meisten Mail-Programmen als zusammenhängender Thread angezeigt:^[79]

Abbildung 5.10. Patch-Serie als Mail-Thread

Das Kommando können Sie über Optionen – beispielsweise --to, --from und --cc – anpassen (siehe die Man-Page git-send-email(1)). Die unbedingt benötigten Angaben werden aber, sofern nicht angegeben, interaktiv abgefragt – vor allem wird eine Adresse benötigt, an die die Patches geschickt werden sollen.^[80]

Bevor die E-Mails tatsächlich versendet werden, wird Ihnen der Header nochmals angezeigt; Sie sollten überprüfen, ob alles Ihren Wünschen entspricht, und anschließend die Frage Send this email? ([y]es|[n]o|[q]uit|[a]ll): mit y für „yes“ beantworten. Um sich mit dem Kommando vertraut zu machen, kann man zunächst alle E-Mails nur an sich selbst schicken oder die Option --dry-run verwenden.

Wenn Sie Ihren bevorzugten Mail User Agent (MUA) (z.B. Thunderbird, Kmail o.a.) verwenden wollen, um Patches zu verschicken, gibt es eventuell einiges zu beachten. Manche MUAs sind berüchtigt, Patches so zu verstümmeln, dass sie Git nicht mehr als solche erkennt.^[83]

Mit git format-patch exportierte Patch-E-Mails werden von dem Git-Kommando git am (apply from mailbox) wieder in Commits zurückübersetzt. Aus jeder E-Mail wird ein neuer Commit erzeugt, dessen Meta-Informationen (Autor, Commit-Message usw.) aus den Header-Zeilen der E-Mail (From, Date) generiert werden. Wie schon erwähnt, erkennt Git an der Nummer im Subject, in welcher Reihenfolge die Commits einzupflegen sind. Um das Beispiel von vorhin zu vollenden: Befinden sich die E-Mails im Maildir-Verzeichnis patches, dann reicht:

$ git am patches
Applying: git-svn.txt: fix usage of --add-author-from
Applying: git-svn.txt: move option descriptions
Applying: git-svn.txt: small typeface improvements

$ git \
  am 0001-git-svn.txt-fix-usage-of-add-author-from.patch
Applying: git-svn.txt: fix usage of --add-author-from

Wenn Sie Patches von Anderen mit git am einpflegen, unterscheiden sich die Werte von Author/AuthorDate und Committer/CommitDate. Somit werden sowohl der Autor des Commits als auch der, der ihn einspielt, gewürdigt. Insbesondere bleiben die Attribuierungen erhalten; es bleibt nachvollziehbar, wer welche Codezeilen geschrieben hat. Mit Gitk werden die Author- und Committer-Werte standardmäßig angezeigt; auf der Kommandozeile setzen Sie die Option --format=fuller ein, die unter anderem von git log und git show akzeptiert wird:

$ git show --format=fuller  12d3065
commit 12d30657d411979af3ab9ca7139b5290340e4abb
Author:     Valentin Haenel <valentin.haenel@gmx.de>
AuthorDate: Mon Apr 25 23:36:15 2011 +0200
Commit:     Junio C Hamano <gitster@pobox.com>
CommitDate: Tue Apr 26 11:48:34 2011 -0700

    git-svn.txt: fix usage of --add-author-from

Bei dem Workflow Dictator and Lieutenants (Abschnitt 5.10, „Ein verteilter, hierarchischer Workflow“) kommt es vor, dass mehr als nur zwei Personen in einen Commit involviert sind. In dem Fall ist es sinnvoll, dass jeder, der den Patch begutachtet, ihn auch „absegnet“, allen voran der Autor. Zu diesem Zweck gibt es die Option --signoff (kurz -s) für die Kommandos git commit und git am, die Name und E-Mail des Committers der Commit-Message anhängt:

Signed-off-by: Valentin Haenel <valentin.haenel@gmx.de>

Das Feature ist vor allem bei größeren Projekten von Vorteil, meist haben diese auch Richtlinien, wie Commits zu formatieren sind und wie sie am besten verschickt werden.^[84]

Beim Einpflegen von Patches mit git am kann es zu Konflikten kommen, z.B. wenn die Patches auf einer älteren Version beruhen und die betreffenden Zeilen bereits verändert wurden. In dem Fall wird der Prozess unterbrochen und Sie haben dann mehrere Möglichkeiten, wie Sie weiter vorgehen. Entweder Sie lösen den Konflikt, aktualisieren den Index und führen den Prozess mit git am --continue fort, oder Sie überspringen den Patch mit git am --skip. Mit git am --abort brechen Sie den Prozess ab und stellen den ursprünglichen Zustand des aktuellen Branches wieder her.

Da die Patches meist Veränderungen von Anderen enthalten, kann es mitunter schwierig sein, die richtige Lösung für einen Konflikt zu finden. Die beste Strategie für Patches, die sich nicht anwenden lassen, ist es, den Autor der Patches zu bitten, diese per Rebase auf eine wohldefinierte Basis, bspw. den aktuellen master, aufzubauen und erneut zu schicken.

Submodules werden von Git als Unterverzeichnisse verwaltet, die einen speziellen Eintrag in der Datei .gitmodules besitzen. Zuständig für den Umgang mit ihnen ist das Kommando git submodule.

Zunächst müssen wir die Bibliothek importieren. Das geschieht mit dem folgenden Kommando:

$ git submodule add git://github.com/libgit2/libgit2.git libgit2
Cloning into libgit2...
remote: Counting objects: 4296, done.
remote: Compressing objects: 100% (1632/1632), done.
remote: Total 4296 (delta 3214), reused 3530 (delta 2603)
Receiving objects: 100% (4296/4296), 1.92 MiB | 788 KiB/s, done.
Resolving deltas: 100% (3214/3214), done.

An der Ausgabe von git status können wir nun erkennen, dass ein neues Verzeichnis libgit2 vorliegt, sowie die Datei .gitmodules mit folgendem Inhalt erstellt wurde:

[submodule "libgit2"]
  path = libgit2
  url = git://github.com/libgit2/libgit2.git

Diese Datei wurde auch schon dem Index hinzugefügt, also für den Commit vorbereitet. Das Verzeichnis libgit2 hingegen taucht in der Ausgabe von git diff --staged nicht wie gewohnt auf:

$ git diff --staged -- libgit2
diff --git a/libgit2 b/libgit2
new file mode 160000
index 0000000..b64e11d
--- /dev/null
+++ b/libgit2
@@ -0,0 +1 @@
+Subproject commit 7c80c19e1dffb4421f91913bc79b9cb7596634a4

Anstatt alle Dateien des Verzeichnisses aufzulisten, speichert Git eine „spezielle“ Datei (erkennbar an dem unüblichen Datei-Modus 160000), die lediglich den Commit, auf dem das Modul gerade steht, festhält.

Wir importieren diese Änderungen und können von nun an die libgit2 in ihrem Unterverzeichnis kompilieren und dann gegen sie linken:

$ git commit -m "libgit2-submodule importiert"

Das übergeordnete Projekt und die libgit2 sind nun im Working Tree zusammengeführt – ihre Versionsgeschichte aber ist und bleibt getrennt. In dem Git-Repository der libgit2 können Sie sich genau so verhalten wie in einem „echten“ Repository. Sie können sich zum Beispiel die Ausgabe von git log in dem übergeordneten Projekt und nach einem cd libgit2 in dem Submodule anschauen.

$ cd libgit2
$ git checkout v0.10.0
# Nachricht über "detached HEAD state"
$ cd ..
$ git diff
diff --git a/libgit2 b/libgit2
index 7c80c19..7064938 160000
--- a/libgit2
+++ b/libgit2
@@ -1 +1 @@
-Subproject commit 7c80c19e1dffb4421f91913bc79b9cb7596634a4
+Subproject commit 7064938bd5e7ef47bfd79a685a62c1e2649e2ce7

$ git add libgit2
$ git commit -m "Libgit2-Version auf v0.10.0 setzen"

$ git clone /dev/shm/super clone-super
$ cd clone-super
$ ls
bar.c  foo.c  libgit2/
$ ls -l libgit2
total 0

$ git submodule init
Submodule 'libgit2' (git://github.com/libgit2/libgit2.git)
registered for path 'libgit2'
$ git submodule update
...
Submodule path 'libgit2': checked out '7064938bd5e7ef47bfd79a685a62c1e2649e2ce7'

Im Gegensatz zu Submodules, die ihren Charakter als eigenständiges Git-Repository wahren, verschmelzen Sie die Geschichte zweier Projekte direkt, wenn Sie mit Subtrees arbeiten. Eine Gegenüberstellung beider Ansätze folgt im Anschluss.

Im Wesentlichen basiert diese Technik auf sogenannten Subtree-Merges, auf die schon kurz in Abschnitt 3.3.3, „Merge-Strategien“ über Merge-Strategien eingegangen wurde. In unserem Beispiel erfolgt ein Subtree-Merge, indem reguläre Commits aus dem Repository der libgit2 unterhalb des Trees (Verzeichnisses) libgit2/ gemergt werden – eine Datei auf oberster Ebene in dem Repository der Bibliothek wird also zu einer Datei auf oberster Ebene des Trees libgit2/, der wiederum Teil eines Repositorys ist.

Git verfügt über ein Kommando, um Subtree-Merges zu verwalten.^[86] Dabei müssen Sie immer explizit durch -P <prefix> angeben, auf welches Unterverzeichnis Sie sich beziehen. Um die libgit2 in Version 0.8.0 zu importieren, verwenden Sie:

$ git subtree add -P libgit2 \
  git://github.com/libgit2/libgit2.git v0.8.0
git fetch git://github.com/libgit2/libgit2.git v0.8.0
From git://github.com/libgit2/libgit2
 * tag               v0.8.0     -> FETCH_HEAD
Added dir 'libgit2'

Das Kommando lädt automatisch alle benötigten Commits herunter und erzeugt einen Merge-Commit, der alle Dateien der libgit2 unterhalb des Verzeichnisses libgit2/ erstellt. Der Merge-Commit verknüpft nun die bisherige Versionsgeschichte mit der der libgit2 (dadurch, dass ein Original-Commit referenziert wird und der wiederum andere Commits referenziert).

Dieses Vorgehen hat nun zur Folge, dass in Ihrem Repository von nun an alle relevanten Commits der libgit2 vorhanden sind. Ihr Repository hat also nun zwei Root-Commits (siehe auch Multi-Root-Repositories in Abschnitt 4.7, „Mehrere Root-Commits“).

Die Dateien liegen nun untrennbar mit dem Projekt verbunden vor. Ein git clone dieses Repositorys würde auch alle Dateien unterhalb von libgit2 übertragen.^[87]

Was passiert nun, wenn Sie ein „Upgrade“ auf v0.10.0 machen wollen? Verwenden Sie dafür das pull-Kommando von git subtree:

$ git subtree -P libgit2 \
  pull git://github.com/libgit2/libgit2.git v0.10.0
From git://github.com/libgit2/libgit2
 * tag               v0.10.0    -> FETCH_HEAD
Merge made by the 'recursive' strategy.
...

Beachten Sie: Da die Original-Commits der libgit2 vorliegen, ändern diese Commits auch scheinbar Dateien auf oberster Ebene (z.B. COPYING, wenn Sie per git log --name-status die Versionsgeschichte untersuchen). Tatsächlich werden diese Änderungen aber in libgit2 ausgeführt – dafür ist der jeweilige Merge-Commit verantwortlich, der die Trees entsprechend ausrichtet.

$ git subtree split -P doc --rejoin
Merge made by the 'ours' strategy.
563c68aa14375f887d104d63bf817f1357482576
$ git push <neues-doku-repo> 563c68aa14375:refs/heads/master

Die Frage „Submodules oder Subtrees?“ lässt sich nicht generell, sondern nur von Fall zu Fall beantworten. Ausschlaggebendes Kriterium sollte die Zugehörigkeit des Unterprojektes zu dem übergeordneten sein: Wenn Sie fremde Software einbinden, dann vermutlich eher als Submodule, eigene mit begrenztem Aufkommen an Commits und einer direkten Relation zum Hauptprojekt eher als Subtree.

Beispielsweise müssen Sie bei der Installation von CGit (siehe Abschnitt 7.5, „CGit – CGI for Git“) ein Submodule initialisieren und updaten, um die libgit.a zu kompilieren. CGit benötigt also den Sourcecode von Git, will aber nicht die Entwicklungsgeschichte mit der von Git verschmelzen (die im Vergleich wenigen CGit-Commits würden darin auch untergehen!). Sie können aber CGit auch gegen eine andere Git-Version kompilieren, wenn Sie das möchten – die Flexibilität des Unter-Repositorys bleibt gewahrt.

Der grafische Repository-Browser Gitk hingegen wird als Subtree verwaltet. Er wird in git://ozlabs.org/~paulus/gitk entwickelt, aber im Haupt-Git-Repository mit der Subtree-Merge-Strategie unterhalb von gitk-git/ eingebunden.