Git Prompt Kit

Git Prompt Kit is a configurable set of components for creating feature rich, high performance Git-aware zsh prompts (aka themes) with minimal coding. It is built on gitstatus, the same accelerated git status alternative used by Powerlevel10k.

Try the interactive demo! https://git-prompt-kit.netlify.app/

• Installation
• Default prompt
• Options
• Components
• Performance
• Acknowledgments
• Changelog
• Contributing
• License

Installation

Shell plugin manager is the recommended installation method.

With a shell plugin manager

1. Install git-prompt-kit with a zsh plugin manager. Each has their own way of doing things. See your package manager's documentation or the zsh plugin manager plugin installation procedures gist.

   After adding the plugin to the manager, restart zsh:

   exec zsh

Manual

Either clone this repo and add source path/to/git-prompt-kit.zsh to your .zshrc, or

1. Download the latest git-prompt-kit binary
2. Put the file git-prompt-kit in a directory in your PATH

Then restart zsh:

exec zsh

Prompt manager

You can use Git Prompt Kit to create a custom, high-performance Spaceship Git section or Starship Git module. Starting points for both are in Recipes.md.

The Git Prompt Kit Spaceship section has been clocked at 50% faster than Spaceship's own Git section. The Git Prompt Kit Starship module has been clocked at about 10% to 30% faster than Starship's own Git module.

Examples

To get a feel for the components try the interactive demo: https://git-prompt-kit.netlify.app/.

See Recipes.md for code how to use Git Prompt Kit components to build a high-performance prompt styled after git-radar, oh-my-git, Pure, or Spaceship.

Hometown is a theme built entirely of Git Prompt Kit components.

Options

Set variables in .zshrc. For example, to only show the user if not me, only show the host if not my-computer or my-other-computer, and use symbols to distinguish between branches and commits:

# ~/.zshrc
# --- snip ---
GIT_PROMPT_KIT_HIDDEN_HOSTS=( my-computer my-other-computer )
GIT_PROMPT_KIT_HIDDEN_USERS=( me )
GIT_PROMPT_KIT_SYMBOL_BRANCH="#"
GIT_PROMPT_KIT_SYMBOL_COMMIT="•"
# Load Git Prompt Kit (will differ depending on installation method)

To output your configuration, for example for sharing, run

git-prompt-kit-config

(The exporter makes an effort to get quoting right, but if you use a custom configuration with quotation marks it's worth double checking that the exported value is correct.)

Behavior options

Color options

Colors can be

• one of zsh's eight color names (black, red, green, yellow, blue, magenta, cyan and white; see http://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#Character-Highlighting)
• an integer 1-255 for an 8-bit color (see https://en.wikipedia.org/wiki/ANSI_escape_code#8-bit)
• or a #-prefixed 3- or 6-character hexadecimal value for 24-bit color (e.g. #fff, #34d5eb)

Support varies by terminal emulator.

Tip: To check a color it can be useful to run print -P %F{<color>}<text>%f, for example print -P %F{199}●%f.

See Issue #1: README appendix: default colors' swatches for the following table but with swatches. They may appear differently in your terminal. To visualize the configured colors in your terminal, run

git-prompt-kit-colors

Content options

Layout options

"Git ref segment" is HEAD, commits ahead/behind, upstream, and tag.

Symbol options

The default symbols should work well in any font. The default Git file status symbols are Git's own short format (underscore _ represents column placement in git-status --short's output).

* %% expands as % in the zsh prompt.

Components

To use Git Prompt Kit's components in a custom prompt, load Git Prompt Kit and then refer to any of its components.

For example, to create the minimal prompt <current working directory> [<Git HEAD> ]% :

Minimal configuration, using Git Prompt Kit for the Git part only:

# ~/.zshrc
# --- snip ---
# Load Git Prompt Kit (will differ depending on installation method)
PROMPT='%1d ${GIT_PROMPT_KIT_HEAD:+$GIT_PROMPT_KIT_HEAD }%% '

Using Git Prompt Kit for everything

# ~/.zshrc
# --- snip ---
# Load Git Prompt Kit (will differ depending on installation method)
GIT_PROMPT_KIT_WORKDIR_DEPTH='2'
PROMPT='$GIT_PROMPT_KIT_WORKDIR ${GIT_PROMPT_KIT_HEAD:+$GIT_PROMPT_KIT_HEAD }$GIT_PROMPT_KIT_CHAR '

Atom components

Molecule components

Other components

Performance

Git Prompt Kit adds less than 10ms to the time between prompts, as measured by zsh-prompt-benchmark. It is built on gitstatus, the same accelerated git status alternative used by Powerlevel10k. See gitstatus for details.

Acknowledgments

Git Prompt Kit is built on Roman Perepelitsa's gitstatus.

Showing "dimmed" components was inspired by Arialdo Martini's oh-my-git, which leaves space for inactive symbols.

Using Git status's short format was inspired by Michael Allen's git-radar.

Splash card font is Beon by Bastien Sozeau.

Changelog

See the CHANGELOG file.

Contributing

Thanks for your interest. Contributions are welcome!

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Check the Issues to see if your topic has been discussed before or if it is being worked on.

Please read CONTRIBUTING.md before opening a pull request.

License

git-prompt-kit by Henry Bley-Vroman is licensed under CC BY-NC-SA 4.0 plus Hippocratic License 3. Persons interested in using or adapting this work for commercial purposes should contact the author.

For the full text of the license, see the LICENSE file.

Download Source Code