diff options
| -rw-r--r-- | README.md | 268 |
1 files changed, 268 insertions, 0 deletions
@@ -8,6 +8,19 @@ 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](#installation) +- [Usage](#usage) +- [Features](#features) + - [Files status](#files-status) + - [Local commits status](#local-commits-status) + - [Remote commits status](#remote-commits-status) + - [(Optional) Auto-fetch repos](#optional-auto-fetch-repos) +- [Support](#support) + - [Ensuring prompt execution](#ensuring-prompt-execution) +- [License](#license) + ## Installation Install from brew: @@ -174,6 +187,261 @@ export PROMPT="\$(git-radar --zsh)" export PS1="\$(git-radar --bash)" ``` +### Configuring colours + +You can configure the colour scheme in two ways: export +[Environment Variables](#exporting-environment-variables) +or use an [rc file](#setting-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`: +```zsh +export GIT_RADAR_COLOR_BRANCH='$fg[yellow]' +``` + +**Example: Change the branch colour in Bash** + +In `~/.bashrc`: +```zsh +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`: +```zsh +GIT_RADAR_COLOR_BRANCH='$fg[yellow]' +``` + +**Basic RC file** + +Create a file at `~/.gitradarrc` which sets the Environment variables listed in +[Configuration values](#configuration-values) using colour codes listed in +either [Zsh Colour Codes](#zsh-colour-codes) or +[Bash Colour Codes](#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. + +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 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. + +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` + +#### 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](#setting-an-rc-file). + +**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. + ## License Git Radar is licensed under the MIT license. |