Options For Git Status in Shell Prompt

• Read time: 6 min

When it comes to customizing your Bash prompt to give you more information about the status of a Git repository, there are a lot of options out there. This post covers using the built-in options that ship with Git, as opposed to a third-party alternatives like this or this.

Once Git is installed, all you need to do is:

  1. Load the git-prompt.sh file (comes with Git) in your ~/.bashrc or ~/.profile file
  2. Add $(__git_ps1) somewhere in your bash prompt variable (look for PS1 in that same files)

The current branch name will always be displayed. However, there are a few other options you can use to add more than just the current branch name to your prompt. The available configurations are not easily Google-able, so I sifted through the source and listed them here. The available options are:

Option Value Description
GIT_PS1_SHOWDIRTYSTATE any nonempty value shows * or a + for unstaged and staged changes, respectively
GIT_PS1_SHOWSTASHSTATE any nonempty value shows $ if there are any stashes
GIT_PS1_SHOWUNTRACKEDFILES any nonempty value shows % if there are any untracked files
GIT_PS1_SHOWUPSTREAM auto shows <, >, <>, or = when your branch is behind, ahead, diverged from, or in sync with the upstream branch, respectively
(alternatively to auto, a space-delimited list of the following options)
verbose show number of commits ahead/behind (+/-) upstream
name if verbose, then also show the upstream abbrev name
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
GIT_PS1_DESCRIBE_STYLE (determines the style of the current commit when in a detached HEAD state, when set to one of the following values)
contains relative to newer annotated tag (e.g., v1.6.3.2~35)
branch relative to newer tag or branch (e.g., master~4)
describe relative to older annotated tag (e.g., v1.6.3.1-13-gdd42c2f)
default exactly matching tag

Here’s how you might put it all together in your ~/.bashrc or ~/.profile file:

# First, load up the git-prompt.sh file that ships with Git. You
# might consider copying it to your home folder first. On my Mac
# OS X (Mavericks) setup, the file resides in
# /Applications/Xcode.app/Contents/Developer/usr/share/git-core/.
test -f ~/git-prompt.sh && . ~/git-prompt.sh

# Then, set the options as desired. Remember that the current
# branch name is displayed no matter what.
export GIT_PS1_SHOWSTASHSTATE=true
export GIT_PS1_SHOWDIRTYSTATE=true
export GIT_PS1_SHOWUNTRACKEDFILES=true
export GIT_PS1_SHOWUPSTREAM="auto"

# Finally, add $(__git_ps1) to the prompt variable. That's it!
PS1="\u@\h \w\$(__git_ps1) \$ "

Here is how the prompt might look:

Git status embedded in bash prompt