Update core documentation as git-sonar manpage

The bulk of README.md is reworked, updated for accuracy, and reformatted
into git-sonar(1).  The output of 'git-sonar --help' is removed as well
(melded into the new manpage).  Now, specifying --help causes the
manpage itself to open.

Since 'git-sonar --help' used to be the only way to ask which version of
the script is installed, a --version output is added as a terse
replacement.

The makefile is updated to facilitate installation of this new
documentation.

Signed-off-by: Matt Hunter <m@lfurio.us>

1 files changed, 498 insertions, 0 deletions

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.