A heads up display for git.
Git-radar is a tool you can add to your prompt to provide at-a-glance information on your git repo. It's a labour of love I've been dogfooding for the last few years. Maybe it can help you too.
Table of Contents
> brew install mcphailtom/homebrew-formulas/git-radar
> cd ~ && git clone https://github.com/mcphailtom/git-radar .git-radar
> echo 'export PATH=$PATH:$HOME/.git-radar' >> ~/.bashrc
Then run git-radar to see the docs and prove it's installed.
To use git-radar you need to add it to your prompt. This is done in different ways depending on your shell.
Bash
Add to your .bashrc
export PS1="$PS1\$(git-radar --bash --fetch)"(note: the \ escaping the $ is important)
Zsh
Add to your .zshrc
export PROMPT="$PROMPT\$(git-radar --zsh --fetch) "(note: the \ escaping the $ is important)
Fish
Add to your config.fish
function fish_prompt
set_color $fish_color_cwd
echo -n (prompt_pwd)
echo -n (git-radar --fish --fetch)
set_color normal
echo -n ' > '
endThe prompt lists the file changes and whether they are staged, unstaged or untracked.
| Prompt | Meaning |
|---|---|
 |
We have 3 untracked files |
 |
We have 2 modifications and 2 deletions not yet staged to commit |
 |
We have 1 modification and a file renamed staged and ready to commit |
 |
We have a conflict caused by US that we need to address |
 |
A combination of the above types |
Each symbol represents a different change to a file. These are based on what git considers has happened to the file.
| Symbol | Meaning |
|---|---|
| A | A new Added file |
| D | A file has been Deleted |
| M | A file has been Modified |
| R | A file has been renamed |
| C | A file has been copied |
| U | A conflict caused by Us |
| T | A conflict caused by Them |
| B | A conflict caused by Both us and them |
The color tells you what stage the change is at.
| Color | Meaning |
|---|---|
| Green | Staged and ready to be committed (i.e. you have done a git add) |
| Red | Unstaged, you'll need to git add them before you can commit |
| Grey | Untracked, these are new files git is unaware of |
| Yellow | Conflicted, these need resolved before they can be committed |
The use of feature is controlled by the GIT_RADAR_FORMAT environment variable.
See Customise your prompt for how to personalise this.
The prompt will show you the difference in commits between your branch and the
remote your branch is tracking. The examples below assume you are checked out on
master and are tracking origin/master.
| Prompt | Meaning |
|---|---|
 |
We have 2 commits to push up |
 |
We have 3 commits to pull down |
 |
Our version and origins version of master have diverged |
The use of feature is controlled by the GIT_RADAR_FORMAT environment variable.
See Customise your prompt for how to personalise this.
The prompt will also show the difference between your branch on origin and what
is on origin/master. This a is hard coded branch name which I intend to make
configurable in the future.
This is the difference between the commits you've pushed up and origin/master.
| Prompt | Meaning |
|---|---|
 |
We have 2 commits on origin/my-branch that aren't on origin/master |
 |
There are 4 commits on origin/master that aren't on origin/my-branch |
 |
origin/master and origin/my-branch have diverged, we'll need to rebase or merge |
The use of feature is controlled by the GIT_RADAR_FORMAT environment variable.
See Customise your prompt for how to personalise this.
The prompt will show you whether and how many stashes you have stored.
| Prompt | Meaning |
|---|---|
 |
We have one stash |
If you don't rely on this status, you can always hide this part of the prompt by customising your prompt
Ensuring your refs are up to date I found can be a pain. To streamline this
git-radar can be configured to auto-fetch your repo. When the --fetch flag is
used git-radar will run git fetch asynchronously every 5 minutes.
This will only occur when the prompt is rendered and it will only occur on the repo you are currently in.
To use this feature, when setting your prompt, call git-radar with --fetch:
Bash
export PS1="$PS1\$(git-radar --bash --fetch)"(note: the \ escaping the $ is important)
Zsh
export PROMPT="$PROMPT\$(git-radar --zsh --fetch) "(note: the \ escaping the $ is important)
You may also choose to fetch at a customized interval of time. To do so, add this to your .bashrc, .zshrc:
export GIT_RADAR_FETCH_TIME=<seconds>For example, to fetch every 30 seconds (instead of the default 5 minutes):
export GIT_RADAR_FETCH_TIME=30You can also do this in the gitradarrc file:
GIT_RADAR_FETCH_TIME=30Git Radar is highly customisable using a prompt format string. The 4 features above: remote commits, local commits, branch and file changes; are controlled by the prompt format string.
| Feature | Control string |
|---|---|
| Remote commits | %{remote} |
| Local commits | %{local} |
| Branch | %{branch} |
| File changes | %{changes} |
| Stashes | %{stash} |
You can create any prompt shape you prefer by exporting GIT_RADAR_FORMAT with
your preferred shape. The control strings above will be replaced with the output
of the corresponding feature.
Examples
| GIT_RADAR_FORMAT | Result |
|---|---|
%{branch}%{local}%{changes} |
master1↑1M |
[%{branch}] - %{local} - %{changes} |
[master] - 1↑ - 1M |
Often you will want certain parts of the prompt to only appear when there is
content to render. For example, when in a repo you want [branch] but when out
of a repo you don't want the [] appearing.
To do this the control strings support prefixes and suffixes. Prefixes and
Suffixes are separated from the feature name by : and will only render if the
feature would render:
Format: prompt > %{prefix - :changes: - suffix}
In a repo: prompt > prefix - 1M - suffix
Outside a repo: prompt >
The default prompt format uses this to add spaces only if the feature would render. In that way the prompt always looks well spaced out no matter how many features are rendering.
When setting your prompt variable, PROMPT in Zsh and PS1 in Bash, it's
important that the function executes each time the prompt renders. That way the
prompt will respond to changes in your git repo. To ensure this you will need
to escape the execution of the function. There are two ways to do this:
1. Use $' to render raw characters
export PROMPT=$'$(git-radar --zsh)'
export PS1=$'$(git-radar --bash)'2. Use \ to escape execution of the subshell
export PROMPT="\$(git-radar --zsh)"
export PS1="\$(git-radar --bash)"You can configure the colour scheme in two ways: export Environment Variables or use an rc file.
To configure the prompt this way just add to your ~/.bashrc or ~/.zshrc an
export directive with the value you want to change.
Example: Change the branch colour in Zsh
In ~/.zshrc:
export GIT_RADAR_COLOR_BRANCH='$fg[yellow]'Example: Change the branch colour in Bash
In ~/.bashrc:
export GIT_RADAR_COLOR_BRANCH='\\033[0;33m'Git radar supports multiple rc files. One of these will be sourced when the prompt renders.
Example: Change the branch colour in Zsh
In ~/.gitradarrc:
GIT_RADAR_COLOR_BRANCH='$fg[yellow]'Basic RC file
Create a file at ~/.gitradarrc which sets the Environment variables listed in
Configuration values using colour codes listed in
either Zsh Colour Codes or
Bash Colour Codes depending on your shell.
Shell specific RC file
If you use both Bash and Zsh you can set RC files that are specific for those shells.
For Bash: Create a file at ~/.gitradarrc.bash
For Zsh: Create a file at ~/.gitradarrc.zsh
Bash colour codes make use of the colours your terminal app claims to be red
or green. Using one of these codes will only produce the colour your terminal
claims, so you should customise your colour scheme on your terminal as well as
customising git-radar.
Note the "Bright" colours can be shown as bold instead, it depends on your terminal. By default, for example, the Mac OSX Terminal.app uses the "Bright" colours to provide 8 new lighter colours but some terminals only support 8 and will show the text as bold instead.
| Colour | Code for Text | Code for Background |
|---|---|---|
| Black | \\033[0;30m |
\\033[0;40m |
| Red | \\033[0;31m |
\\033[0;41m |
| Green | \\033[0;32m |
\\033[0;42m |
| Yellow | \\033[0;33m |
\\033[0;43m |
| Blue | \\033[0;34m |
\\033[0;44m |
| Magenta | \\033[0;35m |
\\033[0;45m |
| Cyan | \\033[0;36m |
\\033[0;46m |
| White | \\033[0;37m |
\\033[0;47m |
| Bright Black | \\033[1;30m |
\\033[1;40m |
| Bright Red | \\033[1;31m |
\\033[1;41m |
| Bright Green | \\033[1;32m |
\\033[1;42m |
| Bright Yellow | \\033[1;33m |
\\033[1;43m |
| Bright Blue | \\033[1;34m |
\\033[1;44m |
| Bright Magenta | \\033[1;35m |
\\033[1;45m |
| Bright Cyan | \\033[1;36m |
\\033[1;46m |
| Bright White | \\033[1;37m |
\\033[1;47m |
| Reset | \\033[0m |
\\033[0m |
Note the Reset will set back to what your terminal claims as standard text and background.
Zsh also provides a way to access the colours that your terminal claims as red
or green, etc.
Note the "Bright" colours can be shown as bold instead, it depends on your terminal. By default, for example, the Mac OSX Terminal.app uses the "Bright" colours to provide 8 new lighter colours but some terminals only support 8 and will show the text as bold instead.
| Colour | Code for Text | Code for Background |
|---|---|---|
| Black | $fg[black] |
$bg[black] |
| Red | $fg[red] |
$bg[red] |
| Green | $fg[green] |
$bg[green] |
| Yellow | $fg[yellow] |
$bg[yellow] |
| Blue | $fg[blue] |
$bg[blue] |
| Magenta | $fg[magenta] |
$bg[magenta] |
| Cyan | $fg[cyan] |
$bg[cyan] |
| White | $fg[white] |
$bg[white] |
| Bright Black | $fg_bold[black] |
$bg_bold[black] |
| Bright Red | $fg_bold[red] |
$bg_bold[red] |
| Bright Green | $fg_bold[green] |
$bg_bold[green] |
| Bright Yellow | $fg_bold[yellow] |
$bg_bold[yellow] |
| Bright Blue | $fg_bold[blue] |
$bg_bold[blue] |
| Bright Magenta | $fg_bold[magenta] |
$bg_bold[magenta] |
| Bright Cyan | $fg_bold[cyan] |
$bg_bold[cyan] |
| Bright White | $fg_bold[white] |
$bg_bold[white] |
| Reset | $reset_color |
$reset_color |
All these values should be set using a the correct colour code for your terminal. You should also choose the colour code based on what shell you are using. There is a way to support colouring multiple shells using rc files.
GIT_RADAR_COLOR_BRANCH='[colour code]'
git:(my-branch)
^^^^^^^^^
The colour to use for the Branch or git reference.
It is unset by
GIT_RADAR_COLOR_BRANCH_RESET which you can set if you want a different
background colour to return to.
GIT_RADAR_COLOR_LOCAL_AHEAD='[colour code]'
git:(my-branch 1↑)
^
The colour to use for the arrow that indicates how many commits you have to push up.
It is unset by GIT_RADAR_COLOR_LOCAL_RESET which you can set if you want
a different background colour to return to.
GIT_RADAR_COLOR_LOCAL_BEHIND='[colour code]'
git:(my-branch 1↓)
^
The colour to use for the arrow that indicates how many commits you have to pull down.
It is unset by GIT_RADAR_COLOR_LOCAL_RESET which you can set if you want
a different background colour to return to.
GIT_RADAR_COLOR_LOCAL_DIVERGED='[colour code]'
git:(my-branch 1⇵1)
^
The colour to use for the arrow that indicates how many commits your branch has diverged by.
It is unset by GIT_RADAR_COLOR_LOCAL_RESET which you can set if you want
a different background colour to return to.
GIT_RADAR_COLOR_REMOTE_AHEAD='[colour code]'
git:(m ← 1 my-branch)
^
The colour to use for the arrow that indicates how many commits your branch has to merge on to master.
It is unset by GIT_RADAR_COLOR_REMOTE_RESET which you can set if you want
a different background colour to return to.
GIT_RADAR_COLOR_REMOTE_BEHIND='[colour code]'
git:(m 1 → my-branch)
^
The colour to use for the arrow that indicates how many commits your branch is behind master.
It is unset by GIT_RADAR_COLOR_REMOTE_RESET which you can set if you want
a different background colour to return to.
GIT_RADAR_COLOR_REMOTE_DIVERGED='[colour code]'
git:(m 1 ⇄ 1 my-branch)
^
The colour to use for the arrow that indicates how many commits your branch has diverged from master.
It is unset by GIT_RADAR_COLOR_REMOTE_RESET which you can set if you want
a different background colour to return to.
GIT_RADAR_COLOR_REMOTE_NOT_UPSTREAM='[colour code]'
git:(upstream ⚡ my-branch)
^
The colour to use for the lightning bolt which indicates that your branch is not tracking an upstream branch.
It is unset by GIT_RADAR_COLOR_REMOTE_RESET which you can set if you want
a different background colour to return to.
GIT_RADAR_COLOR_CHANGES_STAGED='[colour code]'
git:(my-branch) 1M
^
The colour to use for the letters that indicate changes that have been staged to commit.
It is unset by GIT_RADAR_COLOR_CHANGES_RESET which you can set if you want
a different background colour to return to.
GIT_RADAR_COLOR_CHANGES_UNSTAGED='[colour code]'
git:(my-branch) 1M
^
The colour to use for the letters that indicate changes that have not yet been staged to commit.
It is unset by GIT_RADAR_COLOR_CHANGES_RESET which you can set if you want
a different background colour to return to.
GIT_RADAR_COLOR_CHANGES_CONFLICTED='[colour code]'
git:(my-branch) 1B
^
The colour to use for the letters that indicate changes that have conflicts that need resolved.
It is unset by GIT_RADAR_COLOR_CHANGES_RESET which you can set if you want
a different background colour to return to.
GIT_RADAR_COLOR_CHANGES_UNTRACKED='[colour code]'
git:(my-branch) 1A
^
The colour to use for the letters that indicate files that are currently not tracked by git.
It is unset by GIT_RADAR_COLOR_CHANGES_RESET which you can set if you want
a different background colour to return to.
GIT_RADAR_COLOR_STASH='[colour code]'
git:(my-branch) 1≡
^
The colour to use for the lines that indicates how many stashes you have stored.
It is unset by GIT_RADAR_COLOR_STASH_RESET which you can set if you want
a different background colour to return to.
Git Radar is licensed under the MIT license.
See LICENSE for the full license text.
- mini-git-radar - lightweight version of git-radar. Only for macOS and bash/fish.