Skip to content
A fast, customizable, pure-shell, asynchronous Git prompt for Zsh
Branch: master
Clone or download
woefe Fix when git is not available
If git is not installed the prompt always showed `[|✔]`. Fixed by
checking if git is available before installing the precmd hook.
Latest commit ac20119 May 21, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
LICENSE Update copyright year Mar 31, 2019
README.md Improve documentation May 21, 2019
git-prompt.zsh Fix when git is not available May 21, 2019
screenshot.svg Fix screenshot being cut off in some browsers May 6, 2019

README.md

A fast, customizable, pure-shell, asynchronous Git prompt for Zsh. It is heavily inspired by Olivier Verdier's zsh-git-prompt and very similar to the "Informative VCS" prompt of fish shell.

Prompt Structure

The structure of the prompt (in the default configuration) is the following:

[<branch_name><tracking_status>|<local_status>]
  • branch_name: Name of the current branch or commit hash if HEAD is detached. When in 'detached HEAD' state, the branch_name will be prefixed with a colon : to indicate that it is actually a hash and not a branch name.
  • tracking_status:
    • ↑n: ahead of remote by n commits
    • ↓n: behind remote by n commits
    • ↓m↑n: branches diverged; other by m commits, yours by n commits
  • local_status:
    • : repository is clean
    • ✖n: there are n unmerged files
    • ●n: there are n staged files
    • ✚n: there are n unstaged and changed files
    • …n: there are n untracked files
    • ⚑n: there are n entries on the stash (disabled by default)

Installation

Dependencies

  • Git with --porcelain=v2 support, which is available since version 2.11.0. You can check if your installation is compatible by executing git status --branch --porcelain=v2 inside a Git repository.
  • awk, which is most certainly preinstalled on any *nix system

Arch Linux

Install git-prompt.zsh or git-prompt.zsh-git from the AUR. Maintained by Felixoid.

Manual installation

Clone this repo or download the git-prompt.zsh file. Then source it in your .zshrc. For example:

mkdir -p ~/.zsh
git clone --depth=1 https://github.com/woefe/git-prompt.zsh ~/.zsh/git-prompt.zsh
echo "source ~/.zsh/git-prompt.zsh/git-prompt.zsh" >> .zshrc

Customization

Unlike other popular prompts this prompt does not use promptinit, which gives you the flexibility to build your own prompt from scratch. You can build a custom prompt by setting the PROMPT variable in your .zshrc after souring the git-prompt.zsh. And you should use '$(gitprompt)' in your PROMPT to get the Git prompt. You must set your PROMPT with single quotes, not double quotes, otherwise the Git prompt will not update properly. Some example PROMPT configurations are given below. You can find more information on how to configure the PROMPT in Zsh's online documentation or the zshmisc manpage, section "SIMPLE PROMPT ESCAPES".

Examples

You can try these configurations by pasting the variables from below into your running shell. You should restart the shell before pasting a new configuration, otherwise some settings from a previous configuration might remain. And do not forget to save the PROMPT and theming variables to your .zshrc after you found a configuration that you like!

Default (same as in title)

# Preview:
# ../git-prompt.zsh [master↑1|●1✚1…1] ❯❯❯

PROMPT='%B%40<..<%~ %b$(gitprompt)%(?.%F{blue}❯%f%F{cyan}❯%f%F{green}❯%f.%F{red}❯❯❯%f) '

Multi-line prompt

# Preview:
# ┏╸130 · ~/workspace/git-prompt.zsh · ⎇ master↑1 ‹●1✚1…1›
# ┗╸❯❯❯

ZSH_THEME_GIT_PROMPT_PREFIX="%B · %b"
ZSH_THEME_GIT_PROMPT_SUFFIX=""
ZSH_THEME_GIT_PROMPT_SEPARATOR=""
ZSH_THEME_GIT_PROMPT_BRANCH="⎇ %{$fg_bold[cyan]%}"
PROMPT=$'┏╸%(?..%F{red}%?%f · )%B%~%b$(gitprompt)\n┗╸%F{blue}❯%f%F{cyan}❯%f%F{green}❯%f '

Pure clone

# Preview:
#
# ~/workspace/git-prompt.zsh master↑3 ✚2…1
#

ZSH_THEME_GIT_PROMPT_PREFIX=""
ZSH_THEME_GIT_PROMPT_SUFFIX=" "
ZSH_THEME_GIT_PROMPT_SEPARATOR=" "
ZSH_THEME_GIT_PROMPT_DETACHED="%{$fg_no_bold[cyan]%}:"
ZSH_THEME_GIT_PROMPT_BRANCH="%{$fg_no_bold[grey]%}"
ZSH_THEME_GIT_PROMPT_BEHIND="%{$fg_no_bold[cyan]%}↓"
ZSH_THEME_GIT_PROMPT_AHEAD="%{$fg_no_bold[cyan]%}↑"
PROMPT=$'\n%F{blue}%~%f %F{242}$(gitprompt)%f\n%(12V.%F{242}%12v%f .)%(?.%F{magenta}.%F{red})❯%f '

Git status on the right

# Preview:
# ~/workspace/git-prompt.zsh ≻≻≻                                ≺ master↑1|●1✚1…1

ZSH_THEME_GIT_PROMPT_PREFIX=" %{$fg_bold[default]%}≺ "
ZSH_THEME_GIT_PROMPT_SUFFIX=""
PROMPT='%B%~%b %F{blue}≻≻≻%f '
RPROMPT='$(gitprompt)'

Appearance

The appearance of the prompt can be adjusted by changing the variables that start with ZSH_THEME_GIT_PROMPT_. Note that some of them are named differently than in the original Git prompt by Olivier Verdier.

You can preview your configuration by setting the ZSH_THEME_GIT_PROMPT_* variables in a running shell. But remember to save them in your .zshrc after you tweaked them to your liking! Example snippet from .zshrc:

source path/to/git-prompt.zsh
ZSH_THEME_GIT_PROMPT_PREFIX="["
ZSH_THEME_GIT_PROMPT_SUFFIX="] "
ZSH_THEME_GIT_PROMPT_SEPARATOR="|"
ZSH_THEME_GIT_PROMPT_DETACHED="%{$fg_bold[cyan]%}:"
ZSH_THEME_GIT_PROMPT_BRANCH="%{$fg_bold[magenta]%}"
ZSH_THEME_GIT_PROMPT_BEHIND=""
ZSH_THEME_GIT_PROMPT_AHEAD=""
ZSH_THEME_GIT_PROMPT_UNMERGED="%{$fg[red]%}✖"
ZSH_THEME_GIT_PROMPT_STAGED="%{$fg[green]%}●"
ZSH_THEME_GIT_PROMPT_UNSTAGED="%{$fg[red]%}✚"
ZSH_THEME_GIT_PROMPT_UNTRACKED=""
ZSH_THEME_GIT_PROMPT_STASHED="%{$fg[blue]%}⚑"
ZSH_THEME_GIT_PROMPT_CLEAN="%{$fg_bold[green]%}✔"

Show number of stash entries

The number of stash entries will be shown if ZSH_GIT_PROMPT_SHOW_STASH is set. Enabling this will execute a second Git command every time a new prompt is shown! To enable stash entries add the following line to your .zshrc:

ZSH_GIT_PROMPT_SHOW_STASH=1

Change the awk implementation

Some awk implementations are faster than others. By default, the prompt checks for nawk and then mawk and then falls back to the system's default awk. You can override this behavior by setting ZSH_GIT_PROMPT_AWK_CMD to the awk implementation of you liking, before sourcing the git-prompt.zsh. Unlike most other settings of this prompt, ZSH_GIT_PROMPT_AWK_CMD cannot be adjusted in a running shell, but only in your .zshrc.

To benchmark an awk implementation you can use the following command.

# This example tests the default awk. You should change it to something else.
time ZSH_GIT_PROMPT_AWK_CMD=awk zsh -f -c '
    source path/to/git-prompt.zsh
    for i in $(seq 1000); do
        print -P $(_zsh_git_prompt_git_status)
    done'

Features / Non-Features

  • A pure shell implementation using awk; no Python, no Haskell required
  • Uses standard Git, no external Git status daemon (like gitstatus) required
  • Fast; Git command is invoked only once and asynchronously when a new prompt is drawn
  • No caching feature, because it breaks reliable detection of untracked files

Known issues

  • If the current working directory is not a Git repository and some external application initializes a new repository in the same directory, the Git prompt will not be shown immediately. Also, updates made by external programs or another shell do not show up immediately. Executing any command or simply pressing enter will fix the issue.
  • In large repositories the prompt might slow down, because Git has to find untracked files. See man git-status, Section --untracked-files for possible options to speed things up.
You can’t perform that action at this time.