Git Prompt Variables

2 minute read

I recently reinstalled my laptop and had to reconfigure my git prompt. I use the git prompt script that is included in Ubuntu’s git package, and integrate it into my prompt by editing ~/.bashrc, executing source /etc/bash_completion.d/git-prompt, and adding $(__git_ps1) to my PS1 variable, just before the ending \$ (which is the final $ in your prompt).
This gives me a basic prompt, that looks something like:

nitz@computer:~/project (master)$

Note the (master) - that’s the git prompt addition.
However, there are environment variables that can be set before calling git-prompt, that add more information to PS1. I always forget some because I haven’t found an organized list of them, only comments in the git-prompt file itself. I’ve decided to compile my own list.

The Script

I used this nifty script to extract all variables mentioned in the actual git-prompt script with the pattern GIT_PS_*, since it looks like those are the relevant variables.

cat /usr/lib/git-core/git-sh-prompt | perl -nle 'print "$1" if (/(GIT_PS1_[a-zA-Z_]+)/)' | sort | uniq
    Modifies the way detached HEAD is shown. Possible values are:
    • contains: Looks forward in the tree for a tag, so you know which tag you’re behind
    • branch: Looks forward in the tree for a tag or a branch (whatever’s nearest)
    • describe: Looks backwards in the tree for a tag, so you know which tag you’re ahead of
    • default: If your exactly on a tag, display it. If the method you chose fails to find a tag/branch to display, you’ll see the commit id instead.
    __git_ps1 can be used to create the PS1 prompt and not just its own output. If that’s the case, a non-empty value tells git to color the prompt according to the current state (dirty, untracked files…)
    Shows the “dirty” indicator - meaning whether you modified tracked files. Can be * for unstaged changes, + for staged changes, # for “no HEAD to compare against” (usually only happens before initial commit)
    Shows the “stash” indicator - meaning whether you have files stashed.
    Looks like $
  • GIT_PS1_SHOWUNTRACKEDFILES Shows the “untracked” indicator - meaning whether you have untracked files (files that are in the working directory but haven’t been added using git add to the repository).
    Looks like %
    Shows the difference between the upstream branch and the current branch. I only use “auto”, meaning that I get the following values:
    • < when I’m behind (I need to pull to get changes from the server)
    • > when I’m ahead (I need to push to update the server with my changes)
    • <> when I’m diverged from the server (some conflict resolution will be required)
    • = when we’re identical (no action is needed).

    This obviously requires me to fetch the remote server from time to time.

How I did it

My prompt currently looks like this. The if actually sets the prompt and is mostly unmodified (except for adding $(__git_ps1)).

# Git

source /etc/bash_completion.d/git-prompt

if [ "$color_prompt" = yes ]; then
    PS1='${debian_chroot:+($debian_chroot)}\[\033[01;32m\]\u@\h\[\033[00m\]:\[\033[01;34m\]\w\[\033[00m\]$(__git_ps1)\$ '
    PS1='${debian_chroot:+($debian_chroot)}\u@\h:\w$(__git_ps1)\$ '
unset color_prompt force_color_prompt

Tags: ,