Merge branch 'docs'

Completely rewrite documentation, in preparation of the new release.
The README.md file was already a little inaccurate and desynced from the
last tagged git-sonar script, but now that the files have been
redesigned, documentation is in need of a complete face lift.

I've opted to move the meat of the user-facing documentation into
manpages, so that the high fidelity documentation is more accessible on
demand.  This also better opens the door for packaging of git-sonar down
the road, providing some form of documentation that will get 'installed'
along with the tool.

The output of --help for each script is removed, and instead --help will
recall that script's manpage using the 'man' command.  This is done to
make it more obvious that more verbose docs exist, as well as to reduce
the number of spots for documentation that need to be kept in sync.

README is stripped down to function as a higher-level project
information file, which is more focused and easier to navigate now that
usage documentation has its own home.

* docs:
  Replace README with new project information
  precheck: Add documentation in new manpage
  Update core documentation as git-sonar manpage

7 files changed, 650 insertions, 579 deletions

diff --git a/Makefile b/Makefile
index 6edd7f4..e29e455 100644
--- a/Makefile
+++ b/Makefile
@@ -1,4 +1,5 @@
 SOURCE=git-sonar git-precheck
+MANPAGES=git-sonar.1 git-precheck.1
 PREFIX?=/usr/local
 PWD=$(shell pwd)
 
@@ -16,13 +17,14 @@ all:
 	@echo 'If you want to install *git-sonar* for your user only:'
 	@echo '    PREFIX=$$HOME/.local make install'
 
-install: $(SOURCE)
-	@echo 'Installing in' $(PREFIX)/bin '...'
-	mkdir -p $(PREFIX)/bin
+install:
+	@echo 'Installing in' $(PREFIX) '...'
+	mkdir -p $(PREFIX)/bin $(PREFIX)/share/man/man1
 	install -m 755 $(SOURCE) $(PREFIX)/bin
+	install -m 644 $(MANPAGES) $(PREFIX)/share/man/man1
 
-# Link each file separately since the full PWD is needed
-develop: $(SOURCE)
+develop:
+	# Link each file separately since the full PWD is needed
 	@echo 'Symlinking in' $(PREFIX)/bin '...'
 	mkdir -p $(PREFIX)/bin
 	ln -sf $(PWD)/git-sonar $(PREFIX)/bin
diff --git a/README b/README
new file mode 100644
index 0000000..d5f7c3e
--- /dev/null
+++ b/README
@@ -0,0 +1,69 @@
+                     _ _      __                        __  
+                __ _(_) |_ _ / /__  ___  _ __   __ _ _ _\ \ 
+               / _` | | __(_) / __|/ _ \| '_ \ / _` | '__| |
+              | (_| | | |_ _| \__ \ (_) | | | | (_| | |  | |
+               \__, |_|\__(_) |___/\___/|_| |_|\__,_|_|  | |
+               |___/         \_\                        /_/ 
+
+git-sonar is a shell prompt git status indicator, add it to your $PS1 prompt to
+see real-time information about the current directory's repository, branch,
+changed files, etc.  git-sonar is forked from the original project git-radar by
+Michael Allen, which is no longer receiving maintenance.
+Ref: https://github.com/michaeldfallen/git-radar
+
+git-sonar also provides git-precheck, a shell utility script which inspects a
+repository and returns machine-parseable results not easily gathered from
+git status.  It is intended for use in other git-related scripts.
+
+
+INSTALLATION
+------------
+For a normal installation, run 'make install', but see the output from 'make'
+for more installation options.  You can run 'git-sonar --version' to confirm
+that the install was successful.
+
+
+GETTING STARTED
+---------------
+Both of the scripts have an accompanying man-page, which can be viewed after
+installation using the 'man' command, or by passing '--help' to either script
+directly.
+
+These are the user-facing documentation and contain more details about usage,
+configuration, and inserting git-sonar into your particular shell's prompt.
+
+Out of the box, git-sonar has a very usable default configuration, and most
+features are enabled.  One can be up and running by just updating their $PS1
+variable - but see the "USAGE" section of git-sonar's man-page for some possible
+$PS1 pitfalls.
+
+
+GETTING SUPPORT
+---------------
+Get in touch on the mailing list to ask questions, report problems, submit
+patches, or discuss the project!
+
+    git-sonar@normalmode.org
+
+For more information, or instructions on subscribing, send an email to:
+
+    git-sonar+help@normalmode.org
+
+
+COMPATIBILITY WITH GIT-RADAR
+----------------------------
+git-sonar is no longer a "drop in" replacement for git-radar.  All of the
+environment variables used for configuration have been either renamed, or
+removed, and several others have been added.  git-sonar does not read from any
+special RC files, just the shell environment.  Furthermore, both tools support
+different command line options.
+
+git-sonar does preserve the original hallmark features of git-radar, and its
+default appearance is very faithful to the original as well.
+
+
+LICENSE
+-------
+For historical reasons, git-sonar, git-precheck, and associated documentation
+are made available under the MIT license - the same license utilized by
+git-radar.
diff --git a/README.md b/README.md
deleted file mode 100644
index c1155d3..0000000
--- a/README.md
+++ /dev/null
@@ -1,508 +0,0 @@
-# Git Sonar
-
-A heads up display for git.  Fork of 'git-radar' by Michael Allen (https://github.com/michaeldfallen/git-radar).
-
-![An example of git-sonar]
-
-Git-sonar 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)
-  - [Stash status](#stash-status)
-  - [(Optional) Auto-fetch repos](#optional-auto-fetch-repos)
-- [Customise your prompt](#customise-your-prompt)
-- [Support](#support)
-  - [Ensuring prompt execution](#ensuring-prompt-execution)
-  - [Configuring colours](#configuring-colours)
-    - [Exporting Environment Variables](#exporting-environment-variables)
-    - [Setting an RC file](#setting-an-rc-file)
-    - [Colour Codes](#colour-codes)
-    - [Configuration values](#configuration-values)
-      - [Colouring the Branch part](#colouring-the-branch-part)
-      - [Colouring the local commits status](#colouring-the-local-commits-status)
-      - [Colouring the remote commits status](#colouring-the-remote-commits-status)
-      - [Colouring the file changes status](#colouring-the-file-changes-status)
-- [License](#license)
-- [Links](#links)
-
-## Installation
-
-For a normal installation, run 'make install' (may require sudo), but see the
-output from 'make' for more installation options.  Run 'git-sonar -h' to confirm
-the install is successful.
-
-## Usage
-
-To use git-sonar you need to add it to your prompt. This is done in different
-ways depending on your shell.
-
-**Bash**
-
-Add to your `.bashrc`
-```bash
-export PS1="$PS1\$(git-sonar) "
-```
-[(note: the `\` escaping the `$` is important)](#ensuring-prompt-execution)
-
-**Zsh**
-
-Add to your `.zshrc`
-```zsh
-export PROMPT="$PROMPT\$(git-sonar) "
-```
-[(note: the `\` escaping the `$` is important)](#ensuring-prompt-execution)
-
-**Fish**
-
-Add to your `config.fish`
-```bash
-function fish_prompt
-    set_color $fish_color_cwd
-    echo -n (prompt_pwd)
-    echo -n (git-sonar)
-    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
----------------------------|--------
-![git:(master) 3A]         | We have 3 untracked files
-![git:(master) 2D2M]       | We have 2 modifications and 2 deletions not yet staged to commit
-![git:(master) 1M1R]       | We have 1 modification and a file renamed staged and ready to commit
-![git:(master) 1U]         | We have a conflict caused by US that we need to address
-![git:(master) 1M 1D2M 2A] | 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](#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
---------------------|--------
-![git:(master 2↑)]  | We have 2 commits to push up
-![git:(master 3↓)]  | We have 3 commits to pull down
-![git:(master 3⇵5)] | 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](#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 is the difference between the commits you've pushed up and `origin/master`.
-
-Prompt                     | Meaning
----------------------------|---------------
-![git:(m ← 2 my-branch)]   | We have 2 commits on `origin/my-branch` that aren't on `origin/master`
-![git:(m 4 → my-branch)]   | There are 4 commits on `origin/master` that aren't on `origin/my-branch`
-![git:(m 1 ⇄ 2 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](#customise-your-prompt) for how to personalise this.
-
-### Stash status
-The prompt will show you how many stashes you have stored.
-
-Prompt                     | Meaning
----------------------------|---------------
-![git:(master) 1≡]         | 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](#customise-your-prompt)
-
-### (Optional) Auto-fetch repos
-
-Ensuring your refs are up to date I found can be a pain. To streamline this,
-git-sonar can be configured to auto-fetch your repo. When the `--fetch` flag is
-used git-sonar 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.
-
-You may also choose to fetch at a customized interval of time. To do so, add
-this to your .bashrc, .zshrc:
-
-```bash
-export GIT_RADAR_FETCH_TIME=<seconds>
-```
-
-For example, to fetch every 30 seconds (instead of the default 5 minutes):
-
-```bash
-export GIT_RADAR_FETCH_TIME=30
-```
-
-You can also do this in the gitradarrc file:
-
-```bash
-GIT_RADAR_FETCH_TIME=30
-```
-
-## Customise your prompt
-
-Git Sonar 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`
-
-### 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**
-```bash
-export PROMPT=$'$(git-sonar)'
-export PS1=$'$(git-sonar)'
-```
-
-**2. Use `\` to escape execution of the subshell**
-```bash
-export PROMPT="\$(git-sonar)"
-export PS1="\$(git-sonar)"
-```
-
-### 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 sonar 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]'
-```
-
-Create a file at `~/.gitradarrc` which sets the Environment variables listed in
-[Configuration values](#configuration-values) using colour codes listed in
-[Colour Codes](#Colour-Codes).
-
-
-#### Colour Codes
-
-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-sonar.
-
-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.
-
-#### Configuration values
-
-All these values should be set using the correct colour code for your
-terminal.
-
-##### 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 and Git Sonar are licensed under the MIT license.
-
-See [LICENSE] for the full license text.
-
-## Links
-
-* [mini-git-radar](https://github.com/bogem/mini-git-radar) - lightweight version of git-radar. Only for macOS and bash/fish.
-
-[LICENSE]: https://github.com/michaeldfallen/git-radar/blob/master/LICENSE
-[git:(master) 1≡]: https://raw.githubusercontent.com/michaeldfallen/git-radar/master/images/stash.png
-[git:(master) 3A]: https://raw.githubusercontent.com/michaeldfallen/git-radar/master/images/untracked.png
-[git:(master) 2D2M]: https://raw.githubusercontent.com/michaeldfallen/git-radar/master/images/unstaged.png
-[git:(master) 1M1R]: https://raw.githubusercontent.com/michaeldfallen/git-radar/master/images/added.png
-[git:(master) 1U]: https://raw.githubusercontent.com/michaeldfallen/git-radar/master/images/conflicts.png
-[git:(master) 1M 1D2M 2A]: https://raw.githubusercontent.com/michaeldfallen/git-radar/master/images/combination.png
-[git:(master 2↑)]: https://raw.githubusercontent.com/michaeldfallen/git-radar/master/images/local%20is%20ahead.png
-[git:(master 3↓)]: https://raw.githubusercontent.com/michaeldfallen/git-radar/master/images/remote%20is%20behind.png
-[git:(master 3⇵5)]: https://raw.githubusercontent.com/michaeldfallen/git-radar/master/images/remote%20local%20diverged.png
-[git:(m ← 2 my-branch)]: https://raw.githubusercontent.com/michaeldfallen/git-radar/master/images/branch%20is%20ahead.png
-[git:(m 4 → my-branch)]: https://raw.githubusercontent.com/michaeldfallen/git-radar/master/images/master%20is%20ahead.png
-[git:(m 1 ⇄ 2 my-branch)]: https://raw.githubusercontent.com/michaeldfallen/git-radar/master/images/master%20branch%20diverged.png
-[An example of git-radar]: https://raw.githubusercontent.com/michaeldfallen/git-radar/master/images/detailed.png
diff --git a/git-precheck b/git-precheck
index fa42eb3..52f1781 100755
--- a/git-precheck
+++ b/git-precheck
@@ -1,35 +1,6 @@
 #!/bin/sh
 
-usage() {
-    echo "git-precheck [--quiet] [--ignore-dirty] [--ignore-untracked]"
-    echo ""
-    echo "If the current working directory is inside a git repository, examine"
-    echo "the repo for any abnormal state and return an exit code indicating"
-    echo "the status.  If unclean, print a line of text describing each"
-    echo "condition found."
-    echo ""
-    echo "  --quiet"
-    echo "      Don't actually print anything."
-    echo ""
-    echo "  --ignore-dirty"
-    echo "      Don't consider the presence of uncommitted changes to tracked"
-    echo "      files as an abnormal state."
-    echo ""
-    echo "  --ignore-untracked"
-    echo "      Don't consider the presence of untracked files as an abnormal"
-    echo "      state."
-    echo ""
-    echo "  Exit codes:"
-    echo "      0   If inside a repository and all checks return normal"
-    echo "      1   If untracked files detected"
-    echo "      2   If dirty/modified files detected"
-    echo "      3   If any ongoing git operation is in progress"
-    echo "      4   If not inside a git repository"
-    echo ""
-    echo "      Exit any other value on error or if 'precheck' operation is"
-    echo "      not completed, such as when viewing this help text."
-    exit 128
-}
+docs() { exec man 1 git-precheck; }
 
 quiet=""
 opt_dirty="true"
@@ -40,8 +11,8 @@ while true; do
         --quiet) quiet="true" ;;
         --ignore-dirty) opt_dirty="" ;;
         --ignore-untracked) opt_untracked="" ;;
-        --help) usage ;;
-        -h) usage ;;
+        --help) docs ;;
+        -h) docs ;;
         *) break
     esac
     shift
diff --git a/git-precheck.1 b/git-precheck.1
new file mode 100644
index 0000000..e0861b2
--- /dev/null
+++ b/git-precheck.1
@@ -0,0 +1,67 @@
+.TH GIT\-PRECHECK 1 git\-sonar
+
+.SH NAME
+git\-precheck \- detect "unready" state of a git repository
+
+.SH SYNOPSIS
+.B git\-precheck
+.RB [ \-\-quiet ]
+.RB [ \-\-ignore\-dirty ]
+.RB [ \-\-ignore\-untracked ]
+
+.SH DESCRIPTION
+If
+.B git\-precheck
+is run inside a git repository, it examines the repo for any in\-progress git
+operations or unclean state and returns an exit code indicating the status.
+Otherwise,
+.B git\-precheck
+reports that it is not in any git worktree.
+.P
+If
+.B \-\-quiet
+is not given, a line of text is printed describing each condition found.
+
+.SH OPTIONS
+.TP
+.B \-\-quiet
+Don't actually print anything.
+.TP
+.B \-\-ignore\-dirty
+Don't consider the presence of uncommitted changes to tracked files as an
+unclean state.
+.TP
+.B \-\-ignore\-untracked
+Don't consider the presence of untracked files as an unclean state.
+
+.SH EXIT STATUS
+.TP
+.B 0
+If inside a repository and all checks return normal
+.TP
+.B 1
+If untracked files are detected
+.TP
+.B 2
+If dirty/modified files are detected
+.TP
+.B 3
+If any ongoing git operation is in progress
+.TP
+.B 4
+If not inside a git repository
+.P
+.B git\-precheck
+will exit with any other value if an error occurs.
+
+.SH SEE ALSO
+.BR git\-sonar (1),
+.BR git\-status (1)
+
+.SH LICENSE
+.B git\-precheck
+is part of the
+.B git\-sonar
+project, made available under the terms of the
+.B MIT
+license.
diff --git a/git-sonar b/git-sonar
index ee31a65..476375b 100755
--- a/git-sonar
+++ b/git-sonar
@@ -1,38 +1,8 @@
 #!/bin/sh
 
 GIT_SONAR_VERSION="v0.9.0-dev"
-
-usage() {
-    echo "git-sonar [--fetch] [--no-remote-commits] [--no-local-commits]"
-    echo "          [--no-status] [--no-stash]"
-    echo ""
-    echo "git-sonar - a heads up display for git"
-    echo "  $GIT_SONAR_VERSION"
-    echo ""
-    echo "  --fetch"
-    echo "      Periodically fetch from remote repositories asynchronously in"
-    echo "      the background."
-    echo ""
-    echo "  --no-remote-commits"
-    echo "      Disable showing commit counts between current upstream branch"
-    echo "      and the project default branch."
-    echo ""
-    echo "  --no-local-commits"
-    echo "      Disable showing commit counts between the current local and"
-    echo "      upstream branches."
-    echo ""
-    echo "  --no-status"
-    echo "      Disable showing summary of uncommitted changes.  Often faster,"
-    echo "      but omits a lot of information."
-    echo ""
-    echo "  --no-stash"
-    echo "      Disable showing git stash count."
-    echo ""
-    echo "git-sonar is intended to be invoked by your shell prompt and may be"
-    echo "configured through the use of various environment variables.  See"
-    echo "the documentation for more details."
-    exit 0
-}
+version() { exec printf 'git-sonar %s\n' "$GIT_SONAR_VERSION"; }
+docs() { exec man 1 git-sonar; }
 
 opt_fetch=""
 opt_remote="true"
@@ -47,8 +17,10 @@ while true; do
         --no-local-commits) opt_local="" ;;
         --no-status) opt_status="" ;;
         --no-stash) opt_stash="" ;;
-        --help) usage ;;
-        -h) usage ;;
+        --version) version ;;
+        -v) version ;;
+        --help) docs ;;
+        -h) docs ;;
         *) break
     esac
     shift
diff --git a/git-sonar.1 b/git-sonar.1
new file mode 100644
index 0000000..572f815
--- /dev/null
+++ b/git-sonar.1
@@ -0,0 +1,498 @@
+.TH GIT\-SONAR 1 git\-sonar
+
+.SH NAME
+git\-sonar \- a heads up display for git
+
+.SH SYNOPSIS
+.B git\-sonar
+.RB [ options ]
+
+.SH DESCRIPTION
+git\-sonar is a tool you can add to your shell prompt to provide at\-a\-glance
+information about your git repositories.  This includes information such as the
+name of the checked\-out branch, a summary of the
+.B git status
+for modified files, the number of commits which may be pushed or pulled, and
+more.  See the "PROMPT ELEMENTS" section for examples of various possible prompt
+outputs.
+.P
+After installation, git\-sonar is activated by placing a call to the script in
+your shell's
+.B $PS1
+environment variable (or the equivalent).  See the "USAGE" section for
+additional instructions on setting up some common shells.
+.P
+git\-sonar's appearance can be customized by setting various environment
+variables.  See the "CONFIGURATION" section for an exhaustive list of supported
+variables and their descriptions.
+.P
+As an additional feature, git\-sonar may be configured to periodically and
+automatically run
+.B git fetch
+in the repositories your shell visits.  Opt in to this feature by providing
+.B \-\-fetch
+to the git\-sonar command line.
+
+.SH USAGE
+To use git\-sonar, you need to add it to your shell prompt.  This is done in
+different ways depending on your shell.
+.SS bash
+.nf
+# Add to .bashrc
+PS1="...\\$(git-sonar)..."
+.fi
+.SS zsh
+.nf
+# Add to .zshrc
+setopt PROMPT_SUBST
+export GIT_SONAR_COLOR_PREFIX='%{'
+export GIT_SONAR_COLOR_SUFFIX='%}'
+PROMPT='...$(git-sonar)...'
+.fi
+.SS fish
+.nf
+# Add to config.fish
+function fish_prompt
+    # ...
+    echo -n (git-sonar)
+    # ...
+end
+.fi
+.SS Ensuring prompt execution
+When setting the prompt variable, it is crucial that git\-sonar executes each
+time the prompt renders.  This way, the prompt will be able to react to changes
+in the repository.  Some details of the above snippets are necessary to ensure
+this happens:
+.P
+\- bash requires the use of double\-quotes around the value of
+.B $PS1.
+.br
+\- bash requires escaping the call to
+.B git\-sonar
+(add the backslash character).
+.br
+\- zsh requires the use of single\-quotes around the value of
+.B $PROMPT,
+as well as the use of
+.B PROMPT_SUBST.
+
+.SH PROMPT ELEMENTS
+All of the information output by the git\-sonar prompt is implemented by one of
+many prompt elements.  By default, each one is present in the rendered prompt,
+unless it has no information to report.  Each element is named in the form of
+.B %{element},
+as this is the syntax used by the prompt format customization string (see the
+"CONFIGURATION" section for more details).  Furthermore, most elements may be
+disabled by using a command\-line option (see "OPTIONS").
+
+.TP
+.B %{branch}
+Outputs the name of the checked\-out branch.  If
+.B HEAD
+is detached, outputs the abbreviated commit hash.
+
+.nf
+    git:(my-branch)
+    git:(detached@cb39e58e)
+.fi
+
+.TP
+.B %{status}
+Outputs a summary of
+.B git status \-\-porcelain,
+consisting of a count of changed files \- both by change type (addition,
+modification, deletion, etc.) as well as stage (changes staged in the index,
+unmerged, unstaged, or untracked files).
+
+Changes from the same stage are grouped together and color\-coded (see
+"CONFIGURATION" for setting colors).
+
+.nf
+    git:(my-branch) 1\m[green]\fBA\fR\m[] 2\m[red]\fBM\fR\m[]1\m[red]\fBD\fR\m[] 3?
+    git:(my-branch) 2\m[yellow]\fBU\fR\m[]1\m[yellow]\fBD\fR\m[]
+.fi
+
+The first example shows 1 new file staged for commit, 2 unstaged modifications,
+1 unstaged file deletion, as well as 3 untracked files which are unknown to the
+repository.
+
+The second example shows us in the middle of a failed merge, with 2 "both
+modified" unmerged files and 1 file "deleted by them/us".
+
+The change indicators displayed are the same ones used by
+.BR git\-status (1)
+in the
+.B \-\-short
+output format.
+
+.TP
+.B %{stash}
+If any stashed changes are saved, this element outputs the number of stashes
+available with a customizable icon.
+
+.nf
+    git:(my-branch) 2\m[yellow]\fB≡\fR\m[]
+.fi
+
+The example shows 2 stashed changes previously saved in this repository.
+
+.TP
+.B %{local}
+Outputs the number of commits that are different between
+.B HEAD
+and the configured upstream branch
+.B @{u},
+if present.  If there is no upstream branch, or the two are pointing to the
+same commit, nothing is output.
+
+.nf
+    git:(my-branch \m[green]\fB↑\fR\m[]5)
+    git:(my-branch 6\m[red]\fB↓\fR\m[])
+    git:(my-branch 6\m[yellow]\fB⇵\fR\m[]5)
+.fi
+
+In the three examples, the upstream branch is
+.B remotes/origin/my\-branch,
+and we are: ahead by 5 commits, behind by 6 commits, and diverged by 5/6 commits
+respectively.
+
+.TP
+.B %{remote}
+This element functions the same as the
+.B %{local}
+element, except that the upstream branch
+.B @{u}
+is compared to the repository's default branch.
+
+.nf
+    git:(\m[green]\fB↑\fR\m[]5 my-branch)
+    git:(6\m[red]\fB↓\fR\m[] my-branch)
+    git:(6\m[yellow]\fB⇵\fR\m[]5 my-branch)
+.fi
+
+In the three examples, the upstream branch is
+.B remotes/origin/my\-branch,
+the default remote branch is
+.B remotes/origin/master,
+and: my\-branch is ahead by 5 commits, master is ahead by 6 commits, and the two
+are diverged by 5/6 commits respectively.
+
+The default branch is determined automatically.
+
+.TP
+.B %{alert}
+Outputs a customizable icon whenever the repository is in the middle of an
+ongoing operation such as a merge, rebase, bisect, etc., or if the branch's
+configured upstream no longer exists.
+
+.nf
+    git:(\m[yellow]\fB⚡\fR\m[]detached@2fb1cc17)
+.fi
+
+The example shows us in the middle of a bisect session.  Since we are bisecting,
+.B HEAD
+is detached, with the next revision to test checked out.
+
+See also,
+.BR git\-precheck (1).
+
+.P
+Below is a more complete example, showcasing many elements of the prompt
+rendering at once in a fairly complex situation:
+
+.nf
+    o\-\-\-o\-\-\-o\-\-\-o\-\-\-o origin/master
+         \e
+          o\-\-\-o origin/my\-branch
+               \e
+                o\-\-\-o HEAD, my\-branch
+
+    git:(\m[yellow]\fB⚡\fR\m[]3\m[yellow]\fB⇵\fR\m[]2 my-branch \m[green]\fB↑\fR\m[]2) 1\m[yellow]\fB≡\fR\m[] 2\m[green]\fBM\fR\m[] 1\m[yellow]\fBU\fR\m[]
+.fi
+
+.B my\-branch
+is checked out, with the shown branch topology.  A merge from some other commit
+has started, but could not complete automatically.  Two files from the other
+side of the merge have no conflicts and are already staged, however 1 file is in
+conflict and must be resolved.  There is also 1 saved stash being shown.
+
+.SH OPTIONS
+.TP
+.B \-v, \-\-version
+Print the version of git\-sonar and exit.
+
+.TP
+.B \-h, \-\-help
+Display help for git\-sonar (opens this man page).
+
+.TP
+.B \-\-fetch
+git\-sonar will automatically fetch from remote repositories after a
+configurable amount of time passes.  A timestamp of the latest auto\-fetch is
+stored in the
+.B $GIT_DIR/lastupdatetime
+file.  The fetch operation is only triggered when the prompt renders, only runs
+in the repository your shell is in, and executes in the background.
+
+.P
+The remaining options affect the rendered prompt and are provided as a simple
+way to disable features without the need to use a custom prompt format string.
+For more powerful customization, see the "CONFIGURATION" section.
+
+.TP
+.B \-\-no\-remote\-commits
+Disable rendering the
+.B %{remote}
+prompt element, even if it is present in
+.B $GIT_SONAR_PROMPT_FORMAT.
+
+.TP
+.B \-\-no\-local\-commits
+Disable rendering the
+.B %{local}
+prompt element, even if it is present in
+.B $GIT_SONAR_PROMPT_FORMAT.
+
+.TP
+.B \-\-no\-status
+Disable rendering the
+.B %{status}
+prompt element, even if it is present in
+.B $GIT_SONAR_PROMPT_FORMAT.
+For simpler prompts, disabling this feature provides a decent speedup, but omits
+a lot of information.
+
+.TP
+.B \-\-no\-stash
+Disable rendering the
+.B %{stash}
+prompt element, even if it is present in
+.B $GIT_SONAR_PROMPT_FORMAT.
+
+.SH CONFIGURATION
+Colors are customized by using ANSI color codes with the environment variables
+listed below.  However, note that these escape sequences (and any unprintable
+characters used) need to be wrapped in markers that your shell uses to track the
+length of the prompt and handle line wrapping.  These markers will vary by shell
+and it is the responsibility of the user to insert the correct ones when
+exporting overrides for the variables below.  The default colors use markers
+that are compatible with bash.  Overrides for zsh can be seen in the "USAGE"
+section of this document.
+.P
+As a convention for this section, this syntax will be used to denote the use of
+a default color in another variable:
+
+.nf
+    ${<color\-name>} := [prefix marker] \\033[XXXm [suffix marker]
+.fi
+
+In cases where a default color is used, the markers remain configurable using
+a pair of variables below.
+.B XXX
+represents the color attributes required by
+.B <color\-name>.
+
+.TP
+.B $GIT_SONAR_COLOR_PREFIX
+The prefix escape code marker used by default colors.  User provided variables
+must insert their own markers and are unaffected by this value.
+
+Default:
+.B \\\001
+(bash compliant)
+
+.TP
+.B $GIT_SONAR_COLOR_SUFFIX
+The suffix escape code marker used by default colors.  User provided variables
+must insert their own markers are are unaffected by this value.
+
+Default:
+.B \\\002
+(bash compliant)
+
+.TP
+.B $GIT_SONAR_DEFAULT_COLOR
+The color which the terminal is reset to at the end of each prompt element.
+This variable is mainly useful for preserving a background color inside the
+git\-sonar prompt.
+
+Default:
+.B ${reset}
+(all terminal attributes cleared)
+
+.TP
+.B $GIT_SONAR_PROMPT_COLOR
+The text color used by the default prompt format string for the
+.B 'git:(' ')'
+characters surrounding the branch information.  If the user provides their own
+value for
+.B $GIT_SONAR_PROMPT_FORMAT,
+it is unaffected by this value.
+
+Default:
+.B ${bright black}
+
+.TP
+.B $GIT_SONAR_PROMPT_FORMAT
+When inside a git repository, this string controls the format of the output
+produced by git\-sonar.  It functions similarly as a printf\-style format
+string: most characters are output verbatim, and a format specifier syntax is
+used to substitute output from the prompt elements:
+
+.nf
+    %{element-name}
+.fi
+
+If
+.B element\-name
+is either prefixed or suffixed by a colon, the colon delimits a string that is
+affixed to the element output if and only if the element has any output to
+produce.  For example,
+.B %{[:stash:]}
+produces [1\m[yellow]\fB≡\fR\m[]] if a stash is available, but the extra
+brackets are omitted otherwise.  The default format string utilizes this to add
+optional spacing around elements which don't always appear active.
+
+See the "PROMPT ELEMENTS" section for a description of all possible outputs.
+
+.nf
+Default: (space) git:(%{alert}%{remote: }%{branch}%{ :local})%{ :stash}%{ :status}
+.fi
+
+.TP
+.B $GIT_SONAR_FETCH_TIME
+The number of seconds between automatic remote fetches when using
+.B \-\-fetch.
+
+Default:
+.B 300
+(5 minutes)
+
+.TP
+.B $GIT_SONAR_ALERT_ICON
+The symbol shown by the
+.B %{alert}
+prompt element.
+
+Default:
+.B ${yellow}⚡
+
+.TP
+.B $GIT_SONAR_STASH_ICON
+The symbol shown by the
+.B %{stash}
+prompt element.
+
+Default:
+.B ${yellow}≡
+
+.TP
+.B $GIT_SONAR_BRANCH_COLOR
+The text color used by the
+.B %{branch}
+prompt element when on a branch.
+
+Default:
+.B $GIT_SONAR_DEFAULT_COLOR
+
+.TP
+.B $GIT_SONAR_DETACHED_COLOR
+The text color used by the
+.B %{branch}
+prompt element when
+.B HEAD
+is detached.
+
+Default:
+.B $GIT_SONAR_DEFAULT_COLOR
+
+.TP
+.B $GIT_SONAR_STATUS_SEPARATOR
+The string used to separate the different change stages output by the
+.B %{status}
+prompt element.
+
+Default:
+.B (space)
+
+.TP
+.B $GIT_SONAR_AHEAD_ICON
+The symbol shown by the
+.B %{local}
+and
+.B %{remote}
+prompt elements when the primary ref is strictly ahead of the secondary.
+
+Default:
+.B ${green}↑
+
+.TP
+.B $GIT_SONAR_BEHIND_ICON
+The symbol shown by the
+.B %{local}
+and
+.B %{remote}
+prompt elements when the primary ref is strictly behind the secondary.
+
+Default:
+.B ${red}↓
+
+.TP
+.B $GIT_SONAR_DIVERGED_ICON
+The symbol shown by the
+.B %{local}
+and
+.B %{remote}
+prompt elements when the primary and secondary refs each hold unique commits.
+
+Default:
+.B ${yellow}⇵
+
+.TP
+.B $GIT_SONAR_STAGED_COLOR
+The text color used by the
+.B %{status}
+prompt element for change indicators of changes staged in the index.
+
+Default:
+.B ${green}
+
+.TP
+.B $GIT_SONAR_UNSTAGED_COLOR
+The text color used by the
+.B %{status}
+prompt element for change indicators of unstaged changes.
+
+Default:
+.B ${red}
+
+.TP
+.B $GIT_SONAR_UNMERGED_COLOR
+The text color used by the
+.B %{status}
+prompt element for change indicators of unmerged paths (conflicted files).
+
+Default:
+.B ${yellow}
+
+.TP
+.B $GIT_SONAR_UNTRACKED_COLOR
+The text color used by the
+.B %{status}
+prompt element for the untracked file indicator.
+
+Default:
+.B ${white}
+
+.SH SEE ALSO
+.BR git\-fetch (1),
+.BR git\-log (1),
+.BR git\-precheck (1),
+.BR git\-stash (1),
+.BR git\-status (1)
+
+.SH LICENSE
+.B git\-sonar
+is available under the terms of the
+.B MIT
+license.