Readme to describe the colour config

1 files changed, 268 insertions, 0 deletions

diff --git a/README.md b/README.md
index 145f02b..60dbad0 100644
--- a/README.md
+++ b/README.md
@@ -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.