Skip to content

Bash Completion Reference for Git

21/04/2012

The following staff can be found at Git‘s contrib directory and in Bash‘s completion directory, which of course is copied from the first one. I’ve put it here just for easy and quick reference of the relevant information. Further customization of Bash’s prompt is, of course, desirable.The contained completion routines provide support for completing:

  • local and remote branch names
  • local and remote tag names
  • .git/remotes file names
  • git ‘subcommands
  • tree paths within ‘ref:path/to/file‘ expressions
  • common --long-options

To use these routines:

  1. Copy this file to somewhere (e.g. ~/.git-completion.sh).
  2. Add the following line to your .bashrc/.zshrc:
    source ~/.git-completion.sh
  3. Consider changing your PS1 to also show the current branch:

Bash: PS1='[\u@\h \W$(__git_ps1 " (%s)")]\$ '
ZSH:  PS1='[%n@%m %c$(__git_ps1 " (%s)")]\$ '

The argument to __git_ps1 will be displayed only if you are currently in a git repository. The %s token will be the name of the current branch.

In addition, if you set GIT_PS1_SHOWDIRTYSTATE to a nonempty value, unstaged (*) and staged (+) changes will be shown next to the branch name.  You can configure this per-repository with the bash.showDirtyState variable, which defaults to true once GIT_PS1_SHOWDIRTYSTATE is enabled.

You can also see if currently something is stashed, by setting GIT_PS1_SHOWSTASHSTATE to a nonempty value. If something is stashed, then a ‘$’ will be shown next to the branch name.

If you would like to see if there are untracked files, then you can set GIT_PS1_SHOWUNTRACKEDFILES to a nonempty value. If there are untracked files, then a ‘%’ will be shown next to the branch name.

If you would like to see the difference between HEAD and its upstream, set GIT_PS1_SHOWUPSTREAM="auto".  A “<” indicates you are behind, “>” indicates you are ahead, and “<>” indicates you have diverged.  You can further control behaviour by setting GIT_PS1_SHOWUPSTREAM to a space-separated list of values:

  • verbose    show number of commits ahead/behind (+/-) upstream
  • legacy       don’t use the ‘--count‘ option available in recent versions of git-rev-list
  • git               always compare HEAD to @{upstream}
  • svn               always compare HEAD to your SVN upstream

By default, __git_ps1 will compare HEAD to your SVN upstream if it can find one, or @{upstream} otherwise.  Once you have set GIT_PS1_SHOWUPSTREAM, you can override it on a per-repository basis by setting the bash.showUpstream config variable.

Advertisements
Leave a Comment

What do you think?

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: