using git-prompt.sh with colour hints

Now v1.8.1 is out (it was released on December 31st, 2012) the code to make a prompt with git’s status using colour is now in a stable release.

To use it, you don’t need to install the entire release, if you just want to use the colour option, just copy the file contrib/completion/git-prompt.sh to a safe place (e.g. ~/.git-prompt.sh) and make sure you source it in your .bashrc, along with some lines to actually active the code. I’ll show here how to do that.

in your ~/.bashrc add these lines:

if [ -f ~/.git-prompt.sh ]; then
. ~/.git-prompt.sh
GIT_PS1_SHOWDIRTYSTATE=true
GIT_PS1_SHOWCOLORHINTS=true
GIT_PS1_UNTRACKEDFILES=true
PROMPT_COMMAND="__git_ps1 '\u@\h:\w' '\\$ '"
fi

And you’ll get a prompt with colour when inside a directory with a git repository.

The code does the following:

  • test if ~/.git-prompt.sh exists and source it
  • set variables to activate showing git’s state in the prompt, when __git_ps1 is called
    1. GIT_PS1_SHOWDIRTYSTATE; show a * to indicate unstaged files or + for staged files
    2. GIT_PS1_SHOWSTASHSTATE; show that something is in the stash ($)
    3. GIT_PS1_SHOWUNTRACKEDFILES; show files in the current directory that are not being tracked by git
    4. GIT_PS1_SHOWUPSTREAM=”auto”; show upstream status (can be further customised
    5. GIT_PS1_SHOWCOLORHINTS; show in colour what the DIRTY state is, must be used in combination with GIT_PS1_SHOWDIRTYSTATE and PROMPT_COMMAND mode
  • define PROMPT_COMMAND, which is a command ( a function; __git_ps1 in this case) and in order to get __git_ps1 to work properly in this mode, we need to give it two (or three) parameters. The first argument is what is put in the PS1 variable before the status of the git tree, the second argument defines what comes after the status of the git tree in PS1.
  • By default (with just 2 arguments), __git_ps1 will put the string with branch information in a printf format string ” (%s)”. If that isn’t how you want it, you can add a third parameter with a custom format string.

Examples:

  1. branch before the prompt:

    PROMPT_COMMAND="__git_ps1 '' '\u@\h:\w\\$ ' '%s:'"

  2. branch between square brackets:

    PROMPT_COMMAND="__git_ps1 '\u@\h:\w' '\\$ ' ' [%s]' "

You may be wondering: “Why aren’t you setting the PS1 variable?”. The thing is that PROMPT_COMMAND is setting this variable, so we don’t have to (it will be overwritten anyway).

Bash will call the function defined for PROMPT_COMMAND every time it is going to prompt the user for a new command.

Some more links about PROMPT_COMMAND:

The “old” way still works, but colour isn’t possible using command substitution:

PS1='\u@\h:\w $(__git_ps1 "(%s)")\$ '
or
PS1='\u@\h:\w `__git_ps1 "(%s)"`\$ '

edit 9 Jan 2013: explain variables more thoroughly and how the command substitution mode is used.

Post scriptum (3 Jan 2014): Someone else has done this too: https://github.com/magicmonty/bash-git-prompt