Options For Git Status in Shell Prompt

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:

Load the git-prompt.sh file (comes with Git) in your ~/.bashrc or ~/.profile file
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) \$ "