From 23f2b4503c9d7697e382fed550d3bf846b81dd5c Mon Sep 17 00:00:00 2001 From: Peter Stephenson Date: Fri, 19 Sep 2008 12:58:46 +0000 Subject: users/13252 and elsewhere: Frank Terbeck plus tweaks: add VCS_Info function system --- Doc/Zsh/contrib.yo | 336 ++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 334 insertions(+), 2 deletions(-) (limited to 'Doc') diff --git a/Doc/Zsh/contrib.yo b/Doc/Zsh/contrib.yo index 0d3b16aa9..00ebbe335 100644 --- a/Doc/Zsh/contrib.yo +++ b/Doc/Zsh/contrib.yo @@ -11,6 +11,7 @@ such as shell functions, look for comments in the function source files. startmenu() menu(Utilities) +menu(Version Control Information) menu(Prompt Themes) menu(ZLE Functions) menu(Exception Handling) @@ -20,7 +21,7 @@ menu(User Configuration Functions) menu(Other Functions) endmenu() -texinode(Utilities)(Prompt Themes)()(User Contributions) +texinode(Utilities)(Version Control Information)()(User Contributions) sect(Utilities) subsect(Accessing On-Line Help) @@ -316,7 +317,338 @@ functions to be executed. ) enditem() -texinode(Prompt Themes)(ZLE Functions)(Utilities)(User Contributions) +texinode(Version Control Information)(Prompt Themes)(Utilities)(User Contributions) +sect(Gathering information from version control systems) +cindex(version control 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. + +The following VCSs are supported: +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(perforce))(http://www.perforce.com/) +sitem(tt(subversion))(http://subversion.tigris.org/) +sitem(tt(svk))(http://svk.bestpractical.com/) +endsitem() + +To load 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. + +subsect(Quickstart) + +To get this feature working quickly (including colors), you can do the +following (assuming, you loaded var(vcs_info) properly - see above): + +example(zstyle ':vcs_info:*' actionformats \ + '%F{5}(%f%s%F{5})%F{3}-%F{5}[%F{2}%b%F{3}|%F{1}%a%F{5}]%f ' +zstyle ':vcs_info:*' formats \ + '%F{5}(%f%s%F{5})%F{3}-%F{5}[%F{2}%b%F{5}]%f ' +zstyle ':vcs_info:(sv[nk]|bzr):*' branchformat '%b%F{1}:%F{3}%r' +precmd () { vcs_info } +PS1='%F{5}[%F{2}%n%F{5}] %F{3}%3~ ${vcs_info_msg_0_}'"%f%# ') + +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_msg_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 (#) +bzr +cdv +cvs +darcs +git +hg +mtn +p4 +svk +svn +tla +## flavours (cannot be used in the enable or disable styles; they +## are enabled and disabled with their master [git-svn -> git]) +## they *can* be used contexts: ':vcs_info:git-svn:*'. +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. So there is a way to disable +some backends altogether: + +example(zstyle ':vcs_info:*' disable bzr cdv darcs mtn svk tla) + +You may also pick a few from that list and enable only those: + +example(zstyle ':vcs_info:*' enable git cvs svn) + +If you rerun tt(vcs_info_printsys) after one of these commands, you will +see the backends listed in the var(disable) style (or backends not in the +var(enable) style - if you used that) marked as disabled by a hash sign. +That means the detection of these systems is skipped tt(completely). No +wasted time there. + +subsect(Configuration) + +The var(vcs_info) feature can be configured via var(zstyle). + +First, the context in which we are working: +example(:vcs_info:::) + +startitem() +item(tt())( +is one of: git, git-svn, git-p4, hg, darcs, bzr, +cdv, mtn, svn, cvs, svk, tla or p4. +) +item(tt())( +is a freely configurable string, assignable by +the user as the first argument to var(vcs_info) (see its description +below). +) +item(tt())( +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() to +var(zsh) to make it so. +) +enditem() + +There are three special values for tt(): 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 var(formats) and is used by the tt(vcs_info_lastmsg) +for looking up its styles. + +The initial value of tt() 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() is +set up correctly for these only. For all other styles, just use tt('*') +instead. + +There are two pre-defined values for tt(): +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 can of course use tt(':vcs_info:*') to match all VCSs in all +user-contexts at once. + +This is a description of all styles that are looked up. + +startitem() +kindex(formats) +item(tt(formats))( +A list of formats, used when actionformats is not used +(which is most of the time). +) +kindex(actionformats) +item(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). +) +kindex(branchformat) +item(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. +) +kindex(nvcsformats) +item(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_msg_0_}') to accomplish +that. +) +kindex(max-exports) +item(tt(max-exports))( +Defines the maximum number if +var(vcs_info_msg_*_) variables var(vcs_info) will export. +) +kindex(enable) +item(tt(enable))( +A list of backends you want to use. Checked in the +var(-init-) context. If this list contains an item called tt(NONE) no +backend is used at all and var(vcs_info) will do nothing. If this list +contains tt(ALL) var(vcs_info) will use all backends known to it. Only with +tt(ALL) in tt(enable), the tt(disable) style has any effect. tt(ALL) and +tt(NONE) are actually tested case insensitively.) +sitem(tt(disable))(A list of VCSs, you don't want var(vcs_info) to test for +repositories (checked in the var(-init-) context, too). Only used if +tt(enable) contains tt(ALL). +) +kindex(use-simple) +item(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. +) +kindex(use-prompt-escapes) +item(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).) +) +enditem() + +The default values for these styles in all contexts are: + +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))(ALL) +sitem(tt(disable))((empty list)) +sitem(tt(use-simple))(false) +sitem(tt(use-prompt-escapes))(true) +endsitem() + +In normal tt(formats) and tt(actionformats), the following replacements are +done: + +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() + +In tt(branchformat) these replacements are done: + +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 tt(nvcsformats) +no replacements are performed at all. It is just a string. + +subsect(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. + + +subsect(Function descriptions (public API)) + +startitem() +findex(vcs_info) +item(tt(vcs_info) [var(user-context)])( +The main function, that runs all +backends and assembles all data into var(${vcs_info_msg_*_}). 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). If an argument +is given, that string will be used instead of tt(default) in the +user-context field of the style context.) +sitem(tt(vcs_info_lastmsg))(Outputs the last var(${vcs_info_msg_*_}) 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. +) +findex(vcs_info_printsys) +item(tt(vcs_info_printsys) [var(user-context)])( +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_setsys))(Initializes var(vcs_info)'s internal list of +available backends. With this function, you can add support for new VCSs +without restarting the shell. +) +enditem() + +All functions named VCS_INFO_* are for internal use only. + +subsect(Variable description) + +startitem() +item(tt(${vcs_info_msg_N_}) (Note the trailing underscore)) +( +Where var(N) is an integer, eg: var(vcs_info_msg_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_msg_0_}), the second into var(${vcs_info_msg_1_}) +and the Nth into var(${vcs_info_msg_N-1_}). These parameters are +exported into the environment. (See the tt(max-exports) style above.) +) +enditem() + +All variables named VCS_INFO_* are for internal use only. + +subsect(Examples) + +Don't use tt(vcs_info) at all (even though it's in your prompt): +example(zstyle ':vcs_info:*' enable NONE) + +Disable the backends for tt(bzr) and tt(svk): +example(zstyle ':vcs_info:*' disable bzr svk) + +Disable everything em(but) tt(bzr) and tt(svk): +example(zstyle ':vcs_info:*' enable bzr svk) + +Provide a special formats for tt(git): +example(zstyle ':vcs_info:git:*' formats ' GIT, BABY! [%b]' +zstyle ':vcs_info:git:*' actionformats ' GIT ACTION! [%b|%a]') + +Use the quicker tt(bzr) backend +example(zstyle ':vcs_info:bzr:*' use-simple true) + +If you do use tt(use-simple), please report if it does `the-right-thing[tm]'. + +Display the revision number in yellow for tt(bzr) and tt(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 tt(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)(Version Control Information)(User Contributions) sect(Prompt Themes) subsect(Installation) -- cgit 1.4.1