Git Radar

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

• Installation
• Usage
• Features
  • Files status
  • Local commits status
  • Remote commits status
  • Stash status
  • (Optional) Auto-fetch repos
• Customise your prompt
• Support
  • Ensuring prompt execution
  • Configuring colours
    • Exporting Environment Variables
    • Setting an RC file
    • Bash Colour Codes
    • Zsh Colour Codes
    • Configuration values
      • Colouring the Branch part
      • Colouring the local commits status
      • Colouring the remote commits status
      • Colouring the file changes status
• License
• Links

Installation

Install from brew:

> brew install michaeldfallen/formula/git-radar

Manually:

> cd ~ && git clone https://github.com/michaeldfallen/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.

Usage

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 ' > '
end

Features

Files status

The 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.

The color tells you what stage the change is at.

The use of feature is controlled by the GIT_RADAR_FORMAT environment variable. See Customise your prompt for how to personalise this.

Local commits status

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.

Remote commits status

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.

Stash status

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

(Optional) Auto-fetch repos

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=30

You can also do this in the gitradarrc file:

GIT_RADAR_FETCH_TIME=30

Customise your prompt

Git 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.

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

Prefixing and Suffixing the features

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.

Support

Ensuring prompt execution

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)"

Configuring colours

You can configure the colour scheme in two ways: export Environment Variables or use an rc file.

Exporting Environment Variables

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'

Setting an RC file

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

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.

Note the Reset will set back to what your terminal claims as standard text and background.

Zsh Colour Codes

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.

Configuration values

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.

Colouring the Branch part

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.

Colouring the local commits status

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.

Colouring the remote commits status

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.

Colouring the file changes status

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.

Colouring the stash status

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.

License

Git Radar is licensed under the MIT license.

See LICENSE for the full license text.

Links

• mini-git-radar - lightweight version of git-radar. Only for macOS and bash/fish.