zimfw/modules/git-info/README.md

Git-info

Exposes git repository status information to prompts.

Many thanks to Sorin Ionescu and Colin Hebert for the original code.

Git 1.7.2 is the minimum required version.

Settings

Ignore Submodules

Retrieving the status of a repository with submodules can take a long time. Submodules may be ignored when 'none', 'untracked', 'dirty', or 'all', which is the default.

zstyle ':zim:git-info' ignore-submodules 'none'

Verbose Mode

Verbose mode uses git status and computes the count of indexed, unindexed and also untracked files. It can be enabled with the following zstyle:

zstyle ':zim:git-info' verbose 'yes'

In non-verbose mode, the 'untracked' context is not available (see Main Contexts below), and untracked files are also not considered for computing the 'dirty' context. Using git status or checking for untracked files can be expensive.

Theming

To display information about the current repository in a prompt, define your custom styles in the prompt_name_setup function, where the syntax for setting a style is:

zstyle ':zim:git-info:context' format 'string'

Main Contexts

Name	Code	Description
action	%s	Special action name (see Special Action Contexts below)
ahead	%A	Commits ahead of remote count
behind	%B	Commits behind of remote count
diverged	%V	Diverged commits (both ahead and behind are yield when it's not defined)
branch	%b	Branch name
commit	%c	Commit short hash (when in 'detached HEAD' state)
clean	%C	Clean state
dirty	%D	Dirty state (count with untracked files when verbose mode enabled)
indexed	%i	Indexed files (count when verbose mode enabled)
unindexed	%I	Unindexed files (count when verbose mode enabled)
position	%p	Commits from nearest tag count (when in 'detached HEAD' state)
remote	%R	Remote name
stashed	%S	Stashed states count
untracked	%u	Untracked files count (only when verbose mode enabled)

While commit and position are only available when in 'detached HEAD' state, on the other hand, ahead, behind, diverged, branch and remote are only available when an actual branch is checked out (so when not in 'detached HEAD' state).

Special Action Contexts

Name	Format	Default Value
action:apply	value	'apply'
action:bisect	value	'bisect'
action:cherry-pick	value	'cherry-pick'
action:cherry-pick-sequence	value	'cherry-pick-sequence'
action:merge	value	'merge'
action:rebase	value	'rebase'
action:rebase-interactive	value	'rebase-interactive'
action:rebase-merge	value	'rebase-merge'

Formatting example for special actions:

zstyle ':zim:git-info:action:bisect' format '<B>'
zstyle ':zim:git-info:action:merge'  format '>M<'
zstyle ':zim:git-info:action:rebase' format '>R>'

Usage

First, format the repository state attributes. For example, to format the branch name, commit, and remote name, define the following styles:

zstyle ':zim:git-info:branch' format 'branch:%b'
zstyle ':zim:git-info:commit' format 'commit:%c'
zstyle ':zim:git-info:remote' format 'remote:%R'

Second, format how the above attributes are displayed in prompts:

zstyle ':zim:git-info:keys' format \
  'prompt'  'git(%b%c)' \
  'rprompt' '[%R]'

Last, add $git_info[prompt] to $PROMPT and $git_info[rprompt] to $RPROMPT respectively and call git-info in the prompt_name_preexec hook function.