path: root/git-sonar.1

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