Re: Submitting vcs_info function

[Frank Terbeck <ft@xxxxxxxxxxxxxxxxxxx>]

Frank Terbeck <ft@xxxxxxxxxxxxxxxxxxx>:
[...]
> I am attaching the vcs_info file to this mail. And I will post a
> follow-up message, that will contain a documentation patch against
> Doc/Zsh/contrib.yo.

Here is the doc patch.
Note that this is my first stab at yodl documentation, so I'm not
entirely sure if I did it like it's supposed to be. The manpage
renders the way I would expect it to, though.


Index: Doc/Zsh/contrib.yo
===================================================================
RCS file: /cvsroot/zsh/zsh/Doc/Zsh/contrib.yo,v
retrieving revision 1.83
diff -u -r1.83 contrib.yo
--- Doc/Zsh/contrib.yo	24 Jun 2008 16:09:28 -0000	1.83
+++ Doc/Zsh/contrib.yo	17 Sep 2008 20:04:22 -0000
@@ -316,6 +316,321 @@
 )
 enditem()
 
+subsect(Gathering information from version control systems)
+cindex(versioncontrol utility)
+
+In a lot of cases, it is nice to automatically retrieve information from
+version control systems (VCSs), such as subversion, CVS or git, to be able
+to provide it to the user; possibly in the user's prompt. So that you can
+instantly tell on which branch you are currently on,  for example.
+
+In order to do that, you may use the tt(vcs_info) function.
+
+startitem()
+item(Supported VCSs:)(
+findex(supported systems)
+
+startsitem()
+sitem(tt(bazaar))(http://bazaar-vcs.org/)
+sitem(tt(codeville))(http://codeville.org/)
+sitem(tt(cvs))(http://www.nongnu.org/cvs/)
+sitem(tt(darcs))(http://darcs.net/)
+sitem(tt(git))(http://git.or.cz/)
+sitem(tt(gnu arch))(http://www.gnu.org/software/gnu-arch/)
+sitem(tt(mercurial))(http://selenic.com/mercurial/)
+sitem(tt(monotone))(http://monotone.ca/)
+sitem(tt(subversion))(http://subversion.tigris.org/)
+sitem(tt(svk))(http://svk.bestpractical.com/)
+endsitem()
+
+)
+
+Loading var(vcs_info):
+
+example(autoload -Uz vcs_info && vcs_info)
+
+If you plan to use the information from var(vcs_info) in your prompt (which
+is its primary use), you need to enable the tt(PROMPT_SUBST) option.
+
+It can be used in any existing prompt, because it does not require any
+tt($psvar) entries to be left available.
+
+tt(Quickstart)
+findex(vcs_info quickstart)
+
+To get this feature working quickly (including colors), you can do the
+following (assuming, you loaded var(vcs_info) properly - see above):
+
+example(RED=$'%{\e[31m%}'
+GR=$'%{\e[32m%}'
+MA=$'%{\e[35m%}'
+YE=$'%{\e[33m%}'
+NC=$'%{\e[0m%}'
+zstyle ':vcs_info:*' actionformats \ 
+    "${MA}(${NC}%s${MA})${YE}-${MA}[${GR}%b${YE}|${RED}%a${MA}]${NC} "
+zstyle ':vcs_info:*' formats       \ 
+    "${MA}(${NC}%s${MA})${Y}-${MA}[${GR}%b${MA}]${NC}%} "
+zstyle ':vcs_info:(sv[nk]|bzr):*' branchformat "%b${RED}:${YE}%r"
+precmd () { vcs_info }
+PS1="${MA}[${GR}%n${MA}] ${YE}%3~ "'${VCS_INFO_message_0_}'"${NC}%# ")
+
+Obviously, the last two lines are there for demonstration: You need to
+call var(vcs_info) from your var(precmd) function. Once that is done you need
+a tt(single quoted) var('${VCS_INFO_message_0_}') in your prompt.
+
+Now call the tt(vcs_info_printsys) utility from the command line:
+
+example(% vcs_info_printsys
+# list of supported version control backends:
+# disabled systems are prefixed by a hash sign (#)
+git
+hg
+bzr
+darcs
+svk
+mtn
+svn
+cvs
+cdv
+tla
+# flavours (cannot be used in the disable style; they
+# are disabled with their master [git-svn -> git]):
+git-p4
+git-svn)
+
+You may not want all of these. Because there is no point in running the
+code to detect systems you do not use. Ever. So, there is a way to disable
+some backends altogether:
+
+example(zstyle ':vcs_info:*' disable bzr cdv darcs mtn svk tla)
+
+If you rerun tt(vcs_info_printsys) now, you will see the backends listed in
+the var(disable) style marked as diabled by a hash sign. That means the
+detection of these systems is skipped tt(completely). No wasted time there.
+
+tt(Configuration)
+findex(vcs_info configuration)
+
+The var(vcs_info) feature can be configured via var(zstyle).
+
+First, the context in which we are working:
+example(:vcs_info:<vcs-string>:<user-context>:<repo-root-name>)
+
+...where tt(<vcs-string>) is one of: git, git-svn, git-p4, hg, darcs, bzr,
+cdv, mtn, svn, cvs, svk or tla.
+
+...and tt(<user-context>) is a freely configurable string, assignable by
+the user as the first argument to var(vcs_info) (see its description
+below).
+
+...and tt(<repo-root-name>) is the name of a repository in which you want a
+style to match. So, if you want a setting specific to var(/usr/src/zsh),
+with that being a cvs checkout, you can set tt(<repo-root-name>) to
+var(zsh) to make it so.
+
+There is are three special values for tt(<vcs-string>): The first is named
+var(-init-), that is in effect as long as there was no decision what vcs
+backend to use. The second is var(-preinit-); it is used tt(before)
+var(vcs_info) is run, when initializing the data exporting variables. The
+third special value is 'formats' and is used by the tt(vcs_info_lastmsg)
+for looking up its styles.
+
+The initial value of tt(<repo-root-name>) is var(-all-) and it is replaced
+with the actual name, as soon as it is known. Only use this part of the
+context for defining the var(formats), var(actionformats) or
+var(branchformat) styles. As it is guaranteed that tt(<repo-root-name>) is
+set up correctly for these only. For all other styles, just use tt('*')
+instead.
+
+startitem()
+item(There are two pre-defined values for tt(<user-context>):)(
+findex(default_usercontexts)
+
+startsitem()
+sitem(tt(default))(the one used if none is specified)
+sitem(tt(command))(used by vcs_info_lastmsg to lookup its styles)
+endsitem()
+)
+
+You may tt(not) use var(print_systems_) as a user-context string, because
+it is used internally.
+
+You can of course use tt(':vcs_info:*') to match all VCSs in all
+user-contexts at once.
+
+Another special context is var(formats), which is used by the
+tt(vcs_info_lastmsg) utility function (see below).
+
+startitem()
+item(This is a tt(description of all styles), that are looked up:)(
+findex(vcs_info styles)
+
+startsitem()
+sitem(tt(formats))(A list of formats, used when actionformats is not used
+(which is most of the time).)
+sitem(tt(actionformats))(A list of formats, used if a there is a special
+action going on in your current repository; (like an interactive rebase or
+a merge conflict).)
+sitem(tt(branchformat))(Some backends replace var(%b) in the formats and
+actionformats styles above, not only by a branch name but also by a
+revision number. This style let's you modify how that string should look
+like.)
+sitem(tt(nvcsformats))(These "formats" are exported, when we didn't detect
+a version control system for the current directory. This is useful, if you
+want var(vcs_info) to completely take over the generation of your prompt.
+You would do something like tt(PS1='${VCS_INFO_message_0_}') to accomplish
+that.)
+sitem(tt(max-exports))(Defines the maximum number if
+var(VCS_INFO_message_*_) variables var(vcs_info) will export.)
+sitem(tt(enable))(Checked in the var(-init-) context. If set to false,
+var(vcs_info) will do nothing.)
+sitem(tt(disable))(Provide a list of systems, you don't want the
+var(vcs_info) to check for repositories (checked in the var(-init-)
+context, too).)
+sitem(tt(use-simple))(If there are two different ways of gathering
+information, you can select the simpler one by setting this style to true;
+the default is to use the not-that-simple code, which is potentially a lot
+slower but might be more accurate in all possible cases. This style is only
+used by the tt(bzr) backend.)
+sitem(tt(use-prompt-escapes))(Determines if we assume that the assembled
+string from var(vcs_info) includes prompt escapes. (Used by
+tt(vcs_info_lastmsg).))
+endsitem()
+
+)
+
+startitem()
+item(The tt(default values) for these styles in all contexts are:)(
+findex(vcs_info style defaults)
+
+startsitem()
+sitem(tt(formats))(" (%s)-[%b|%a]-")
+sitem(tt(actionformats))(" (%s)-[%b]-")
+sitem(tt(branchformat))("%b:%r" (for bzr, svn and svk))
+sitem(tt(nvcsformats))("")
+sitem(tt(max-exports))(2)
+sitem(tt(enable))(true)
+sitem(tt(disable))((empty list))
+sitem(tt(use-simple))(false)
+sitem(tt(use-prompt-escapes))(true)
+endsitem()
+
+)
+
+startitem()
+item(In normal formats and actionformats, the following replacements are
+done:)(
+findex(vcs_info format expansions)
+
+startsitem()
+sitem(tt(%s))(The vcs in use (git, hg, svn etc.))
+sitem(tt(%b))(Information about the current branch.)
+sitem(tt(%a))(An identifier, that describes the action. Only makes sense in
+actionformats.)
+sitem(tt(%R))(base directory of the repository.)
+sitem(tt(%r))(repository name. If tt(%R) is var(/foo/bar/repoXY), tt(%r) is
+var(repoXY).)
+sitem(tt(%S))(subdirectory within a repository. If tt($PWD) is
+var(/foo/bar/reposXY/beer/tasty), tt(%S) is var(beer/tasty).)
+endsitem()
+
+)
+
+startitem()
+item(In tt(branchformat) these replacements are done:)(
+findex(vcs_info branchformat expansions)
+
+startsitem()
+sitem(tt(%b))(the branch name)
+sitem(tt(%r))(the current revision number)
+endsitem()
+
+)
+
+Not all vcs backends have to support all replacements. For var(nvcsformats)
+no replacements are performed at all. It is just a string.
+
+tt(Oddities)
+
+If you want to use the tt(%b) (bold off) prompt expansion in var(formats),
+which expands tt(%b) itself, use tt(%%b). That will cause the var(vcs_info)
+expansion to replace tt(%%b) with tt(%b). So zsh's prompt expansion
+mechanism can handle it. Similarly, to hand down tt(%b) from
+var(branchformat), use tt(%%%%b). Sorry for this inconvenience, but it
+cannot be easily avoided. Luckily we do not clash with a lot of prompt
+expansions and this only needs to be done for those.
+
+
+startitem()
+item(tt(Function descriptions (public API)))(
+findex(vcs_info functions)
+
+startsitem()
+sitem(tt(vcs_info))(The main function, that runs all backends and assembles
+all data into var(${VCS_INFO_message_*_}). This is the function you want to
+call from tt(precmd) if you want to include up-to-date information in your
+prompt (see Variable description below).)
+sitem(tt(vcs_info_printsys))(Prints a list of all supported version control
+systems. Useful to find out possible contexts (and which of them are
+enabled) or values for the var(disable) style.)
+sitem(tt(vcs_info_lastmsg))(Outputs the last var(${VCS_INFO_message_*_})
+value. Takes into account the value of the use-prompt-escapes style in
+var(':vcs_info:formats:command:-all-'). It also only prints tt(max-exports)
+values.)
+endsitem()
+
+All functions named VCS_INFO_* are for internal use only.
+
+)
+
+startitem()
+item(tt(Variable description))(
+findex(vcs_info variables)
+
+startsitem()
+sitem(tt(${VCS_INFO_message_N_}) (Note the trailing underscore))(
+Where var(N) is an integer, eg: var(VCS_INFO_message_0_) These variables
+are the storage for the informational message the last var(vcs_info) call
+has assembled. These are strongly connected to the formats,
+tt(actionformats) and tt(nvcsformats) styles described above. Those styles
+are lists. The first member of that list gets expanded into
+var(${VCS_INFO_message_0_}), the second into var(${VCS_INFO_message_1_})
+and the Nth into var(${VCS_INFO_message_N-1_}). These parameters are
+exported into the environment. (See the tt(max-exports) style above.))
+endsitem()
+
+)
+
+tt(Examples)
+
+Don't use vcs_info at all (even though it's in your prompt):
+example(zstyle ':vcs_info:*' enable false)
+
+Disable the backends for bzr and svk:
+example(zstyle ':vcs_info:*' disable bzr svk)
+
+Provide a special formats for git:
+example(zstyle ':vcs_info:git:*' formats       ' GIT, BABY! [%b]'
+zstyle ':vcs_info:git:*' actionformats ' GIT ACTION! [%b|%a]')
+
+Use the quicker bzr backend
+example(zstyle ':vcs_info:bzr:*' use-simple true)
+
+If you do use use-simle, please report if it does tt(the-right-thing[tm]).
+
+Display the revision number in yellow for bzr and svn:
+example(zstyle ':vcs_info:(svn|bzr):*' branchformat '%b%{'${fg[yellow]}'%}:%r')
+
+If you want colors, make sure you enclose the color codes in tt(%{...%}),
+if you want to use the string provided by var(vcs_info) in prompts.
+
+Here is how to print the vcs infomation as a command (not in a prompt):
+example(alias vcsi='vcs_info command; vcs_info_lastmsg')
+
+This way, you can even define different formats for output via
+tt(vcs_info_lastmsg) in the ':vcs_info:formats:command:*' namespace.
+
+
 texinode(Prompt Themes)(ZLE Functions)(Utilities)(User Contributions)
 sect(Prompt Themes)