Git: Distributed Version Control for Code and Documents

To activate the completion, load the script with the command source and pass the corresponding file as argument, e.g:

The completion completes among other things:

As usual with bash completion, the input is automatically completed when it is unique. If only the Branch feature exists, typing git checkout fe[TAB] will cause fe to be completed; the command git checkout feature will then appear on the command line - press Enter to execute the command. Only when the input is ambiguous does the bash display the possible completions.

Beside the completion there is another script to display information about the git repository in the prompt. For this you have to load the file contrib/completion/git-prompt.sh (maybe it is also installed by your distribution, e.g. under /usr/lib/git-core/git-sh-prompt). Then, as in the following example, place a call to the __git_ps1 function in the PS1 variable. The function takes a so-called _format string expression_ as argument - i.e. the string %s is replaced by git infos, all other characters are taken over.

The characters are replaced as follows: \u is the username, \h is the hostname, \w is the current working directory and $(__git_ps1 " (%s)") are the git infos, which without additional configuration (see below) consist only of the branch name:

The format string expression allows you to customize the display of the git info by using additional characters or color codes, e.g. with the following prompt:

This looks like this:

If the current commit is not referenced by a branch (Detached-HEAD), either the tag or the abbreviated SHA-1 sum is displayed, each surrounded by a pair of brackets:

If you are inside the $GIT_DIR or in a bare repository, this is signaled accordingly:

It also indicates when you are in the middle of a merge, rebase or similar state where only certain operations are possible:

You can also expand the display to show the status of the Working Trees using different icons. To do this, you must set the following environment variables to a non-empty value, e.g. to 1.

You can activate all this additional information as follows:

If everything in the repository matches (i.e. unstaged, staged, stashed and untracked), four additional characters (*, +, $ and %) are displayed in the prompt:

In newer Git versions, the script has a new feature that shows the relationship to the upstream branch (@{upstream}). Enable this feature by setting GIT_PS1_SHOWUPSTREAM to the value git.⁠^[134] The prompt then signals all states described in Section 5.5.2, "Comparison with the Upstream": up-to-date with the equal sign (=); ahead with the greater-than sign (>); behind with the less-than sign (<); diverged with both a greater-than sign and a less-than sign (><). For example:

This function is implemented with the --count option of the git rev-list plumbing command, which does not exist in old git versions, like 1.7.1. If you have such an old git version, but a current script and want to use this display anyway, set the value of the environment variable to legacy - the script will then use an alternative implementation that works without the said option. If you also want to know how far ahead or behind the branch is, add the value verbose. The prompt will also show the number of different commits:

The desired values are to be assigned to the environment variable as a list:

To activate completion for Git, first load the completion system:

The completion completes among other things:

A big difference with the Z-Shell is the way it is completed. The Z-Shell uses the so-called menu completion. This means that the Z-Shell offers you the next possible completion by pressing the Tab key again.⁠^[135]

The Z-Shell is not (yet) able to complete references on the remote side - but this is on the to-do list. But the Z-Shell is already able to complete files over an SSH connection. This is especially useful in connection with public key authentication and preconfigured SSH hosts. Assume you have configured the following host in .ssh/config:

On the server in your home directory your projects are located as bare repositories: project1.git and project2.git. You also generated an SSH key and stored it in the .ssh/authorized_keys file on the server. You can now use completion across the SSH connection.

This is made possible by the completion functions of the Z-shell for ssh.

The Z-Shell contains functions to add git info to the prompt. The functionality is part of the extensive vcs_info system, which knows about a dozen other version control programs besides Git, including Subversion, CVS and Mercurial. Detailed documentation can be found in the zshcontrib(1) man page, in the “Gathering Information From Version Control Systems” section. Here we will only present the settings and customization options relevant to Git.

First, you need to load vcs_info and adjust the prompt to display Git info. It’s important that the Z-Shell option prompt_subst is set; it ensures that variables in the prompt are actually replaced, and you must call vcs_info in the precmd function. precmd is called just before the prompt is displayed. The call vcs_info in it makes sure that the git info is actually stored in the variable ${vcs_info_msg_0_}. Add the following lines to your .zshrc if they are not already included:

The prompt is composed as follows: %n is the username, %m is the hostname, %~ is the current working directory, and the variable ${vcs_info_msg_0_} contains the git info. It is important that the prompt is specified with single quotes. This saves the string ${vcs_info_msg_0_} and not the value of the variable. Only when the prompt is displayed is the value of the variable - i.e. the git info - substituted.

The above setting for PS1 looks like this:

Since vcs_info works with a lot of version control systems, it’s worth activating only those you actually use:⁠^[136]

To customize vcs_info, use a so-called zstyle, a hierarchical configuration mechanism of the z-shell described in the zshmodules(1) man page.

Special states like merge or rebase operations are signaled accordingly:

Also in case of a Detached-HEAD either the tag or the abbreviated SHA-1 sum is displayed:

The Z-Shell, like the Bash, can display states of the working tree. Switch this on with the following line:

For example, vcs_info shows a U for changes that are not yet in the index (unstaged) and an S for changes that you have included in the index (staged):

A big advantage of vcs_info is that it can be adapted very easily. For example, if you do not like the letters U and S, you can replace them with other characters, e.g. * and +:

Thus the Zsh prompt now looks more and more like the example from the section on bash:

To display such not yet stored information vcs_info must always examine the working tree. Since this is known to cause problems with large repositories, you can exclude certain patterns:

Maybe you want to change the order of the characters. In this case you need to adjust two format string expressions: formats and actionformats. The first is the default format, the second is the format when you are in the middle of a merge, rebase or similar process:

A selection of the most important characters can be found in the following table. For a detailed list, please refer to the above mentioned man page.

With the above setting the prompt will look like this:

Unfortunately vcs_info cannot signal the existence of unknown files and created stashes by default. But since Z-Shell version 4.3.11 the system supports so called hooks — extensions, which inject additional information into the prompt. We will now introduce two such hooks, which implement the two missing features mentioned above.

The hooks for vcs_info are written as shell functions. Note that the function name has the prefix +vi- to avoid possible collisions. For a hook to really work it has to change a value in the associative array hook_com. In both examples we change the value of the entry staged by appending additional characters to mark certain states. We use the percent sign (%) to indicate unknown files and the dollar sign ($) for created stashes. The percent sign must be specified twice to prevent the Z-Shell from mistakenly interpreting it as formatting. For the hooks we use various plumbing commands (see Sec. 8.3, “Writing Your Own Git Commands”).

We activate the hooks so that they are evaluated when the git info is set (+set-message):

As in the bash example above, four additional characters (*, +, $ and %) may be displayed in the prompt (unstaged, staged, stashed and untracked):

With such hooks it is possible to extend the prompt as desired. For example, vcs_info does not show by default whether you are inside the $GIT_DIR or in a bare repository. With an appropriate hook you can include these signals in the prompt.

For more examples, see the Misc/vcs_info-examples file in the Z-Shell repository, including a hook that indicates the upstream branch relationship (section “Compare local changes to remote changes”). A minimal configuration for the Z-Shell according to the examples in this section can be found in the Scripts Collection for this book.⁠^[137]