kenglxn / git-radar

A heads up display for git

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.

Installation

Install from brew:

> brew install michaeldfallen/formula/git-radar

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

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

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

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

If you don't rely on this status, you can always hide this part of the prompt by calling git-radar with --no-remote-status.

Bash

export PS1="$PS1\$(git-radar --bash --fetch --no-remote-status) "

(note: the \ escaping the $ is important)

Zsh

export PROMPT="$PROMPT\$(git-radar --zsh --fetch --no-remote-status) "

(note: the \ escaping the $ is important)

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

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

License

Git Radar is licensed under the MIT license.

See LICENSE for the full license text.