Kapitel 10. Shell-Integration

Um die Completion zu aktivieren, laden Sie das Script mit dem Befehl source und übergeben als Argument die entsprechende Datei, also z.B.:

source ~/Downloads/git-2.1.0/contrib/completion/git-completion.bash

Die Completion vervollständigt unter anderem:

Wie bei der Bash-Completion üblich, wird die Eingabe automatisch vervollständigt, sobald sie eindeutig ist. Existiert nur der Branch feature, führt die Eingabe von git checkout fe[TAB] dazu, dass fe vervollständigt wird; der Befehl git checkout feature steht dann auf der Kommandozeile – drücken Sie auf Enter, um den Befehl auszuführen. Nur wenn die Eingabe nicht eindeutig ist, zeigt die Bash die möglichen Vervollständigungen an.

Neben der Completion gibt es ein weiteres Script, um Infos über das Git-Repository im Prompt anzuzeigen. Dafür müssen Sie die Datei contrib/completion/git-prompt.sh laden (ggf. ist diese auch von Ihrer Distribution installiert, z.B. unter /usr/lib/git-core/git-sh-prompt). Setzen Sie anschließend – wie in folgendem Beispiel – einen Aufruf der Funktion __git_ps1 in die Variable PS1 ein. Als Argument nimmt die Funktion einen sogenannten Format-String-Ausdruck entgegen – d.h. die Zeichenfolge %s wird durch Git-Infos ersetzt, alle anderen Zeichen werden übernommen.

source /usr/lib/git-core/git-sh-prompt
PS1='\u@\h \w$(__git_ps1 " (%s)") $ '

Die Zeichen werden wie folgt ersetzt: \u ist der Benutzername, \h der Rechnername, \w ist das aktuelle Arbeitsverzeichnis und $(__git_ps1 " (%s)") sind die Git-Infos, die ohne zusätzliche Konfiguration (s.u.) nur aus dem Branch-Namen bestehen:

esc@creche ~ $ cd git-working/git
esc@creche ~/git-working/git (master) $

Mit dem Format-String-Ausdruck passen Sie die Darstellung der Git-Infos an, indem Sie zusätzliche Zeichen oder aber Farbcodes nutzen, z.B. mit folgendem Prompt:

PS1='\u@\h \w$(__git_ps1 " (git)-[%s]") $ '

Das sieht dann so aus:

esc@creche ~/git-working/git (git)-[master] $

Ist der aktuelle Commit nicht durch einen Branch referenziert (Detached-HEAD), wird entweder das Tag oder die abgekürzte SHA-1-Summe angezeigt, jeweils von einem Klammerpaar umgeben:

esc@creche ~/git-working/git (git)-[(v1.7.1.4)] $
esc@creche ~/git-working/git (git)-[(e760924...)] $

Befinden Sie sich innerhalb des $GIT_DIR oder in einem Bare-Repository, wird dies entsprechend signalisiert:

esc@creche ~/git-working/git/.git (git)-[GIT_DIR!] $
esc@creche ~/git-working/git.git/.git (git)-[BARE:master] $

Außerdem wird angezeigt, wenn Sie sich mitten in einem Merge-Vorgang, einem Rebase oder einem ähnlichem Zustand befinden, bei dem nur bestimmte Operationen möglich sind:

esc@creche ~/git-working/git (git)-[master|REBASE-i] $

Sie können die Anzeige auch erweitern, um sich den Zustand des Working Trees durch verschiedene Symbole anzeigen zu lassen. Sie müssen dazu folgende Umgebungsvariablen auf einen Non-Empty-Wert setzen, also z.B. auf 1.

Alle diese Zusatzinformationen können Sie wie folgt aktivieren:

GIT_PS1_SHOWDIRTYSTATE=1
GIT_PS1_SHOWSTASHSTATE=1
GIT_PS1_SHOWUNTRACKEDFILES=1

Wenn im Repository nun alles zutrifft (also unstaged, staged, stashed und untracked) werden vier zusätzliche Zeichen (*, +, $ und %) im Prompt angezeigt:

esc@creche ~/git-working/git (git)-[master *+$%] $

In neueren Git-Versionen verfügt das Script über ein neues Feature, das die Beziehung zum Upstream-Branch (@{upstream}) anzeigt. Aktivieren Sie diese Funktion durch Setzen von GIT_PS1_SHOWUPSTREAM auf den Wert git.^[134] Das Prompt signalisiert dann alle Zustände, die in Abschnitt 5.5.2, „Vergleich mit dem Upstream“ beschrieben sind: up-to-date mit dem Gleichheitszeichen (=); ahead mit dem Größer-als-Zeichen (>); behind mit dem Kleiner-als-Zeichen (<); diverged mit sowohl einem Größer-als-Zeichen und einem Kleiner-als-Zeichen (><). Zum Beispiel:

esc@creche ~/git-working/git (git)-[master >] $

Diese Funktion ist mit der Option --count des Plumbing-Kommandos git rev-list implementiert, die in alten Git-Versionen, etwa 1.7.1, noch nicht existiert. Haben Sie eine solche alte Git-Version, aber ein aktuelles Script und wollen diese Anzeige trotzdem verwenden, setzen Sie den Wert der Umgebungsvariablen auf legacy – das Script verwendet dann eine alternative Implementation, die ohne die besagte Option auskommt. Wenn Sie außerdem noch wissen wollen, wie weit der Branch vorne bzw. zurück liegt, fügen Sie den Wert verbose hinzu. Das Prompt zeigt dann auch noch die Anzahl der unterschiedlichen Commits an:

esc@creche ~/git-working/git (git)-[master u+2] $

Die gewünschten Werte sind der Umgebungsvariable als Liste zuzuweisen:

GIT_PS1_SHOWUPSTREAM="legacy verbose git"

$ man[ESC]+[h]
#Man-Page man(1) wird angezeigt

$ git rebase[ESC]+[h]
#Man-Page git(1) wird angezeigt
$ unalias run-help
$ autoload run-help
$ autoload run-help-git
$ git rebase[ESC]+[h]
#Man-Page git-rebase(1) wird angezeigt

Um die Completion für Git zu aktivieren, laden Sie zunächst das Completion-System:

$ autoload -Uz compinit && compinit

Die Completion vervollständigt unter anderem:

Ein großer Unterschied bei der Z-Shell ist die Art und Weise, wie vervollständigt wird. Die Z-Shell verwendet die sogenannte Menu-Completion. Das bedeutet, dass Ihnen die Z-Shell durch erneutes Drücken der Tab-Taste jeweils die nächste mögliche Vervollständigung anbietet.^[135]

$ git pu[TAB]
pull  -- fetch from and merge with another repository or local branch
push  -- update remote refs along with associated objects
$ git pu[TAB]
$ git pull[TAB]
$ git push

Die Z-Shell ist (noch) nicht in der Lage, Referenzen auf der Remote-Seite zu vervollständigen – dies steht jedoch auf der To-do-Liste. Die Z-Shell ist aber heute schon in der Lage, Dateien über eine SSH-Verbindung hinweg zu vervollständigen. Besonders nützlich ist dies im Zusammenhang mit Public-Key-Authentifizierung und vorkonfigurierten SSH-Hosts. Angenommen, Sie haben folgenden Host in .ssh/config konfiguriert:

Host example
    HostName git.example.com
    User max

Auf dem Server in Ihrem Home-Verzeichnis befinden sich Ihre Projekte als Bare-Repositories: projekt1.git und projekt2.git. Außerdem haben Sie einen SSH-Schlüssel generiert und diesen in der Datei .ssh/authorized_keys auf dem Server abgelegt. Sie können nun die Vervollständigung über die SSH-Verbindung hinweg nutzen.

$ git clone example:[TAB]
projekt1.git/ projekt2.git/

Möglich wird dies durch die Completion-Funktionen der Z-Shell für ssh.

Die Z-Shell beinhaltet Funktionen, um das Prompt mit Git-Infos zu versehen. Die Funktionalität ist Teil des umfangreichen vcs_info-Systems, das neben Git circa ein Dutzend anderer Programme zur Versionsverwaltung kennt, inklusive Subversion, CVS und Mercurial. Die ausführliche Dokumentation finden Sie in der Man-Page zshcontrib(1), im Abschnitt „Gathering Information From Version Control Systems“. Hier stellen wir nur die für Git relevanten Einstellungen und Anpassungsmöglichkeiten vor.

Zunächst müssen Sie vcs_info laden und das Prompt so anpassen, dass Git-Infos angezeigt werden. Hierbei ist wichtig, dass die Z-Shell-Option prompt_subst gesetzt ist; sie sorgt dafür, dass Variablen im Prompt auch tatsächlich ersetzt werden, außerdem müssen Sie die Funktion vcs_info in der Funktion precmd aufrufen. precmd wird direkt vor der Anzeige des Prompts aufgerufen. Der Aufruf vcs_info darin sorgt dafür, dass die Git-Infos auch tatsächlich in der Variable ${vcs_info_msg_0_} gespeichert werden. Fügen Sie Ihrer .zshrc folgende Zeilen hinzu, falls sie noch nicht enthalten sind:

# vcs_info laden
autoload -Uz vcs_info
# prompt_subst aktivieren
setopt prompt_subst
# precmd definieren
precmd () { vcs_info }
# Prompt setzten
PS1='%n@%m %~${vcs_info_msg_0_} $ '

Das Prompt setzt sich wie folgt zusammen: %n ist der Benutzername, %m ist der Rechnername, %~ das aktuelle Arbeitsverzeichnis und die Variable ${vcs_info_msg_0_} enthält die Git-Infos. Wichtig ist dabei, dass das Prompt mit einfachen Anführungszeichen (single quotes) angegeben wird. Dadurch wird die Zeichenfolge ${vcs_info_msg_0_} und nicht der Wert der Variablen abgespeichert. Erst bei Anzeige des Prompt wird der Wert der Variablen – also die Git-Infos – substituiert.

Die o.g. Einstellung für PS1 sieht so aus:

esc@creche ~/git-working/git (git)-[master]- $

Da vcs_info mit sehr vielen Versionsverwaltungssystemen funktioniert, lohnt es sich, nur diejenigen zu aktivieren, die Sie tatsächlich verwenden:^[136]

zstyle ':vcs_info:*' enable git

Zum Anpassen von vcs_info verwenden Sie einen sogenannten zstyle, einen hierarchischen Konfigurationsmechanismus der Z-Shell, der in der Man-Page zshmodules(1) beschrieben ist.

Besondere Zustände wie Merge- oder Rebase-Vorgänge werden entsprechend signalisiert:

esc@creche ~/git-working/git (git)-[master|bisect]- $

Auch bei einem Detached-HEAD wird entweder das Tag oder die abgekürzte SHA-1-Summe angezeigt:

esc@creche ~/git-working/git (git)-[v1.7.1.4] $
esc@creche ~/git-working/git (git)-[e760924...] $

Die Z-Shell kann, wie die Bash auch, Zustände des Working Trees anzeigen. Schalten Sie dies mit folgender Zeile an:

zstyle ':vcs_info:git*:*' check-for-changes true

So zeigt vcs_info für Veränderungen, die noch nicht im Index sind (unstaged), ein U an und für Veränderungen, die Sie im Index aufgenommen haben (staged), ein S:

esc@creche ~/git-working/git (git)-[master]US- $

Ein großer Vorteil von vcs_info ist, dass es sich sehr leicht anpassen lässt. Gefallen Ihnen etwa die Buchstaben U und S nicht, können Sie sie durch andere Zeichen z.B. * und + ersetzen:

zstyle ':vcs_info:git*:*' unstagedstr '*'
zstyle ':vcs_info:git*:*' stagedstr '+'

Somit ähnelt das Zsh-Prompt nun immer mehr dem Beispiel aus dem Abschnitt zur Bash:

esc@creche ~/git-working/git (git)-[master]*+- $

Um solche noch nicht gespeicherten Informationen anzuzeigen, muss vcs_info immer den Working Tree untersuchen. Da dies bei großen Repositories bekanntlich Probleme bereitet, können Sie bestimmte Muster ausschließen:

zstyle ':vcs_info:*' disable-patterns "/home/esc/git-working/linux-2.6(|/*)"

Vielleicht möchten Sie nun noch die Reihenfolge der Zeichen ändern. In dem Fall müssen Sie zwei Format-String Ausdrücke anpassen: formats und actionformats. Der erste ist das Standardformat, der zweite das Format, wenn Sie sich mitten in einem Merge-Vorgang, Rebase oder ähnlichem befinden:

zstyle ':vcs_info:git*:*' formats " (%s)-[%b%u%c]"
zstyle ':vcs_info:git*:*' actionformats " (%s)-[%b|%a%u%c]"

Eine Auswahl der wichtigsten Zeichen finden Sie in der folgenden Tabelle. Eine detaillierte Auflistung bietet die oben erwähnte Man-Page.

Mit der o.g. Einstellung sieht das Prompt dann so aus:

esc@creche ~/git-working/git (git)-[master*+] $

Leider kann vcs_info standardmäßig die Existenz unbekannter Dateien und angelegter Stashes nicht signalisieren. Das System unterstützt aber ab Z-Shell Version 4.3.11 sogenannte Hooks – Erweiterungen, die zusätzliche Information in das Prompt einschleusen. Wir werden nun zwei solcher Hooks vorstellen, die die beiden genannten, fehlenden Features implementieren.

Die Hooks für vcs_info werden als Shell-Funktionen geschrieben. Beachten Sie, dass der Funktionsname das Präfix +vi- hat, um mögliche Kollisionen zu vermeiden. Damit ein Hook auch wirklich funktioniert, muss er einen Wert im assoziativen Array hook_com verändern. In beiden Beispielen verändern wir den Wert des Eintrags staged, indem wir zusätzliche Zeichen anhängen, um bestimmte Zustände zu markieren. Wir verwenden das Prozent-Zeichen (%), um unbekannte Dateien zu signalisieren, und das Dollar-Zeichen ($) für angelegte Stashes. Das Prozentzeichen muss zweimal angegeben werden, damit die Z-Shell es nicht fälschlich als Formatierung wertet. Bei den Hooks greifen wir auf diverse Plumbing-Kommandos zurück (siehe Abschnitt 8.3, „Eigene Git-Kommandos schreiben“).

+vi-untracked(){
    if [[ $(git rev-parse --is-inside-work-tree 2> /dev/null) == 'true' ]] && \
        [[ -n $(git ls-files --others --exclude-standard) ]] ; then
        hook_com[staged]+='%%'
    fi
}
+vi-stashed(){
    if git rev-parse --verify refs/stash &> /dev/null ; then
        hook_com[staged]+='$'
    fi
}

Wir aktivieren die Hooks, so dass sie beim Setzen der Git-Infos ausgewertet werden (+set-message):

zstyle ':vcs_info:git*+set-message:*' hooks stashed untracked

Wie beim Beispiel zu der Bash oben, werden ggf. (unstaged, staged, stashed und untracked) vier zusätzliche Zeichen (*, +, $ und %) im Prompt angezeigt:

esc@creche ~/git-working/git (git)-[master*+$%] $

Mit solchen Hooks ist es möglich, das Prompt nach Belieben zu erweitern. Zum Beispiel zeigt vcs_info standardmäßig nicht an, ob Sie sich innerhalb des $GIT_DIR oder aber in einem Bare-Repository befinden. Mit einem entsprechenden Hook bauen Sie diese Signale in das Prompt ein.

Weitere Beispiele finden sich in der Datei Misc/vcs_info-examples des Z-Shell Repositorys, unter anderem auch ein Hook, der die Beziehung zum Upstream-Branch anzeigt (Abschnitt „Compare local changes to remote changes“). Eine minimale Konfiguration für die Z-Shell entsprechend den Beispielen in diesem Abschnitt finden Sie in der Scriptsammlung für dieses Buch.^[137]