geometry is a minimalistic, fully customizable zsh prompt theme.
geometry starts small, with good defaults, and allows you to customize it at your own will. It can be as simple or complex as you like.
K, I'm sold. Beam me up, Scotty.
Just add antigen theme geometry-zsh/geometry
to your .zshrc
.
Move the entire geometry
folder to $HOME/.oh-my-zsh/custom/themes
, and set ZSH_THEME="geometry/geometry"
in your .zshrc
.
Add zplug "geometry-zsh/geometry"
to your .zshrc
.
Clone this repository as follows:
git clone https://github.com/geometry-zsh/geometry
cd geometry
git submodule update --init --recursive
Then add it to your .zshrc
configuration:
source /path/to/geometry/geometry.zsh
The symbol for rebasing comes from a Powerline patched font. If you want to use it, you're going to need to install one from the font repo. The font used in the screenshots is Roboto Mono. You can also try to patch it yourself.
You can also change the rebase symbol by setting the GEOMETRY_SYMBOL_GIT_REBASE
variable.
To allow a pleasant configuration and customization, geometry works with the concept of plugins.
In a nutshell, it can:
- give you a custom, colorizable prompt symbol
- change the prompt symbol color according to the last command exit status
- make the prompt symbol color change with your hostname
- display current git branch, state and time since last commit
- tell you whether you need to pull, push or if you're mid-rebase
- display the number of conflicting files and total number of conflicts
- display the running time of long running commands
- set the terminal title to current command and directory
- make you the coolest hacker in the whole Starbucks
The right side prompt is printed asynchronously, so you know it's going to be fast™.
geometry has an internal plugin architecture. The default plugins are exec_time
, git
and hg
.
But you can enable a variety of built-in plugins just by setting the GEOMETRY_PROMPT_PLUGINS
variable in your own configuration files:
GEOMETRY_PROMPT_PLUGINS=(virtualenv docker_machine exec_time git hg)
Note: if you're not sure where to put geometry configs, just add them to your .zshrc
.
These plugins will load and display on the right prompt. You can check the documentation and configuration for each specific plugin in the plugins directory.
Some plugins only render when you are in a given directory or in the presence of a given file.
You can have those plugins always render by pinning a +
before the name.
export GEOMETRY_PROMPT_PLUGINS=(exec_time git +rustup) # rustup will always render
geometry also supports your own custom plugins. See the plugin documentation for instructions and examples.
Please check out and share third-party plugins on our Plugins wiki page.
geometry was built with easy configuration in mind. The best way to do so is by using environment variables.
Pretty much everything in geometry can be changed by setting a variable before you load the theme.
The default options try to balance the theme in order to be both lightweight and contain useful features.
There are a set of symbols available which you can override with environment variables.
GEOMETRY_SYMBOL_PROMPT="▲" # default prompt symbol
GEOMETRY_SYMBOL_RPROMPT="◇" # multiline prompts
GEOMETRY_SYMBOL_EXIT_VALUE="△" # displayed when exit value is != 0
GEOMETRY_SYMBOL_ROOT="▲" # when logged in user is root
You can find symbol configuration for specific plugins under the plugins directory.
The following color definitions are available for configuration:
GEOMETRY_COLOR_EXIT_VALUE="magenta" # prompt symbol color when exit value is != 0
GEOMETRY_COLOR_PROMPT="white" # prompt symbol color
GEOMETRY_COLOR_ROOT="red" # root prompt symbol color
GEOMETRY_COLOR_DIR="blue" # current directory color
You can find color configuration for specific plugins under the plugins directory.
GEOMETRY_PROMPT_PREFIX="$'\n'" # prefix prompt with a new line
GEOMETRY_PROMPT_SUFFIX="" # suffix prompt
GEOMETRY_PLUGIN_SEPARATOR=" " # use ' ' to separate right prompt parts
GEOMETRY_GREP="" # define which grep-like tool to use (By default it looks for rg, ag and finally grep)
geometry runs RPROMPT
asynchronously to avoid blocking on costly operations. This is enabled by default but you can disable it by setting PROMPT_GEOMETRY_RPROMPT_ASYNC
to false
.
Your prompt symbol can change colors based on a simple hash of your hostname. To enable this, set PROMPT_GEOMETRY_COLORIZE_SYMBOL
to true
.
You can have your prompt symbol change color when running under the root
user.
To activate this option, just set PROMPT_GEOMETRY_COLORIZE_ROOT
to true
. Both symbol and color can be customized by overriding the GEOMETRY_SYMBOL_ROOT
and GEOMETRY_COLOR_ROOT
variables.
Note that this option overrides the color hashing of your prompt symbol.
You can optionally show a time display for long-running commands
by setting the PROMPT_GEOMETRY_EXEC_TIME
variable to true
.
If enabled, this shows the elapsed time for commands running longer than 5 seconds. You can change this threshold by changing PROMPT_GEOMETRY_COMMAND_MAX_EXEC_TIME
to the number of desired seconds.
I found a bug. What do I do?
Open an issue. There are probably more people with that very same problem so we like to keep everything documented in case someone else comes looking for a solution.
If you can provide info about your terminal, OS and zsh version it would be a great starting point. It would also be of great assistance if you are able to write steps to reproduce the issue.
I have an idea for a feature, can I submit a PR?
Please do. geometry is a work in progress, so if you want to help improve it, your idea is welcome. We're not looking to add a lot of default features to not overload the theme. However, plugins are a great way of extending geometry without overloading it. If you have an idea for a plugin, feel free to submit it and we'll always give our best to provide constructive feedback and help you improve.
Is there anything specific I can do to help?
There are always things we would like to improve. Feel free to jump in on any issue to tackle it or just to provide your feedback.
As for PRs, we are currently looking to improve performance.
Why doesn't my prompt look like the screenshots?
Well, I use z
for jumping around and
zsh-syntax-highlighting
for those pretty command colors. You might also want to look into base16 to get similar colors.
Where do I put my geometry configuration files?
Well, anywhere in your .zshrc
file should be fine, as long as you define
variables before geometry is loaded.
My tab completion is weird.
This is a known problem due to the use of unicode characters. It should be fixed right now. If it persists, update geometry and check if the terminal version reported by zsh matches your terminal emulator reported version. Please comment on that thread if any new issues arise.
There are too many/few spaces after the symbol or the prompt.
You're probably using a different prompt character. zsh has a few issues determining the length of the prompt and while it should work for most cases, changing the symbol to a different character (an example would be: ☁︎ )
will result in a few extra spaces after the prompt. That problem is documented here and there is no known fix for it except on a case-by-case basis. You can add or remove any extra space through the prompt_geometry_render
function in geometry.zsh
. If you find a universal solution, feel free to make a PR for it.
The prompt is slow on large repos.
This is also a known issue. Make sure you have PROMPT_GEOMETRY_RPROMPT_ASYNC
set to true
to avoid long waiting times. If the problem persists, our recommendation would be to disable the git time checks by setting PROMPT_GEOMETRY_GIT_TIME
to false
.
That's a neat font you have there. Can I have it?
Sure. It's Roboto Mono. Don't forget to use the powerline patched version if you want to use the default rebase symbol.
"Warning: Plugin already registered." omg what is happening is the world going to end?
Well, yeah. Eventually. But this warning message doesn't mean anything is wrong.
Feel free to relax. It shows when you load geometry twice. It was intended as a
warning for faulty custom configuration, such as registering a plugin in two
different places. If you do source ~/.zshrc
it's perfectly normal to show up.
See this discussion for more info.
geometry is currently maintained by fribmendes, desyncr and jedahan.
A big thank you to those who have previously contributed.