Options For Git Status in Shell Prompt
Published: 2020-06-29 12:44:43

---
title: Options For Git Status in Shell Prompt
published: true
date: 2014-08-08 04:01:00 UTC
tags: 
canonical_url: https://mjswensen.com/blog/git-status-prompt-options/
---

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](https://github.com/magicmonty/bash-git-prompt) or [this](https://github.com/lvv/git-prompt).

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](https://raw.githubusercontent.com/git/git/master/contrib/completion/git-prompt.sh) 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:

```sh
# 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](https://mjswensen.com/blog/images/git-prompt.png)