Repository files navigation

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

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

[<branch_name><upstream><tracking_status>|<local_status>]

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

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

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

mkdir -p~/.zshgit clone --depth=1 https://github.com/woefe/git-prompt.zsh~/.zsh/git-prompt.zshecho"source ~/.zsh/git-prompt.zsh/git-prompt.zsh">> .zshrc# Optional: install an example configurationecho"source ~/.zsh/git-prompt.zsh/examples/pure.zsh">> .zshrc

Either install the default prompt (seeExamples section below) with

# Installs the "default" examplezplug "woefe/git-prompt.zsh"

or choose an example prompt with

# Installs the "multiline" examplezplug "woefe/git-prompt.zsh", use:"{git-prompt.zsh,examples/multiline.zsh}"

zplugin ice atload'!_zsh_git_prompt_precmd_hook' lucidzplugin load woefe/git-prompt.zsh

Note that this method does not work if you want to disable the asynchronous rendering.

Installgit-prompt.zsh orgit-prompt.zsh-git from the AUR.Maintained byFelixoid.

Install thegit-prompt.zsh package with

pkg install git-prompt.zsh

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

Seeexamples/README.md for more details.

The prompt comes with a secondary function that shows the tags that HEAD points to.Enabling this will execute another Git command every time a new prompt is shown!To use the secondary prompt you have to enable it and add the'gitprompt_secondary' function to yourPROMPT orRPROMPT variables.You enable the secondary prompt by adding the following line to your.zshrc:

ZSH_GIT_PROMPT_ENABLE_SECONDARY=1

The secondary prompt uses thelabel emoji by default.If you encounter problems with the label character, change it (see below) or install a font that can display it, for exampleUnifont ortwemoji.

The appearance of the prompt can be adjusted by changing the variables that start withZSH_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 theZSH_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:

# Theming variables for primary promptZSH_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_UPSTREAM_SYMBOL="%{$fg_bold[yellow]%}⟳"ZSH_THEME_GIT_PROMPT_UPSTREAM_NO_TRACKING="%{$fg_bold[red]%}!"ZSH_THEME_GIT_PROMPT_UPSTREAM_PREFIX="%{$fg[red]%}(%{$fg[yellow]%}"ZSH_THEME_GIT_PROMPT_UPSTREAM_SUFFIX="%{$fg[red]%})"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]%}✔"# Theming variables for the secondary promptZSH_THEME_GIT_PROMPT_SECONDARY_PREFIX=""ZSH_THEME_GIT_PROMPT_SECONDARY_SUFFIX=""ZSH_THEME_GIT_PROMPT_TAGS_SEPARATOR=","ZSH_THEME_GIT_PROMPT_TAGS_PREFIX="🏷"ZSH_THEME_GIT_PROMPT_TAGS_SUFFIX=""ZSH_THEME_GIT_PROMPT_TAG="%{$fg_bold[magenta]%}"source path/to/git-prompt.zsh

The prompt will show information about the remote branch, ifZSH_GIT_PROMPT_SHOW_UPSTREAM is set tofull orsymbol.Thefull option will print the full remote branch name enclosed byZSH_THEME_GIT_PROMPT_UPSTREAM_PREFIX andZSH_THEME_GIT_PROMPT_UPSTREAM_SUFFIX.Thesymbol option prints onlyZSH_THEME_GIT_PROMPT_UPSTREAM_SYMBOL.

Furthermore, a warning symbol can be configured throughZSH_THEME_GIT_PROMPT_UPSTREAM_NO_TRACKING for the case where no remote is available.ZSH_THEME_GIT_PROMPT_UPSTREAM_NO_TRACKING can be set independently ofZSH_GIT_PROMPT_SHOW_UPSTREAM.

IfZSH_GIT_PROMPT_SHOW_STASH is set, the prompt will display a symbol and the number of stash entries when there are entries in the stash.On Git versions older than 2.35.0 this will execute another 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

By default, the prompt will show counts for each item in the tracking status and local status sections (seePrompt Structure for details about these sections).However, you can disable the display of counts for either or both sections of the prompt usingZSH_GIT_PROMPT_SHOW_TRACKING_COUNTS andZSH_GIT_PROMPT_SHOW_LOCAL_COUNTS.If you unset these variables or set them to0, then only the symbols will be shown but not the counts.For example, a prompt such as[master|✚2] will become[master|✚] instead.

Since the prompt is asynchronous by default, the Git status updates slightly delayed.This has the benefit that the prompt will always be responsive even if the repository is huge and/or your disk is slow.But it also means that the old status will be displayed for some time.You can force the prompt to blank out instead of displaying a potentially outdated status, but be warned that this will probably increase flickering.Set the following variable in your.zshrc to enable this behavior:

ZSH_GIT_PROMPT_FORCE_BLANK=1

If you are not happy with the asynchronous behavior, you can disable it altogether.But be warned that this can make your shell painfully slow if you enter large repositories or if your disk is slow.Set the following variable in your.zshrcbefore sourcing thegit-prompt.zsh to enable this behavior.

ZSH_GIT_PROMPT_NO_ASYNC=1

ZSH_GIT_PROMPT_NO_ASYNC cannot be adjusted in a running shell, but only in your.zshrc.

Some awk implementations are faster than others.By default, the prompt checks fornawk and thenmawk and then falls back to the system's default awk.You can override this behavior by settingZSH_GIT_PROMPT_AWK_CMD to the awk implementation of you likingbefore sourcing thegit-prompt.zsh.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'

• A pure shell implementation usingawk; no Python, no Haskell required
• Only the Git status.This prompt basically only gives you thegitprompt function, which you can use to build your own prompt.If you are looking for something more complete and blazing fast, I can recommendpowerlevel10k.
• Uses standard Git, no external Git status daemon (likegitstatus) 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

• 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 to draw a new prompt will fix the issue.
• In large repositories the prompt might slow down, because Git has to find untracked files.Seeman git-status, Section--untracked-files for possible options to speed things up.