name : vcs_info-examples ## vim:ft=zsh # # A collection of vcs_info usage examples ### Running vcs_info ######################################################### # As always, there's more than one way to skin a cat. Running vcs_info is no # exception. Here is a rundown of three common ways to get it into action. # # All three ways need vcs_info to be marked for autoloading first, so you'd # do this somewhere in your setup: autoload -Uz vcs_info # Episode I: "The prompt_subst way" # Also known as the Quick-Start-Way. Probably the simplest way to add # vcs_info functionality to existing setups. You just drop a vcs_info call # to your `precmd' (or into a `precmd_functions[]' entry) and include a # single-quoted ${vcs_info_msg_0_} in your PS1 definition: precmd() { vcs_info } # This needs prompt_subst set, hence the name. So: setopt prompt_subst PS1='%!-%3~ ${vcs_info_msg_0_}%# ' # Episode II: "The way of the psvar" # With $psvar you got a simple way to get user defined things into your # prompt without having to set `prompt_subst', which requires extra # attention to quoting if you like characters like ` in your prompt... # As described in <http://xana.scru.org/xana2/quanks/vcsinfoprompt/>: precmd() { psvar=() vcs_info [[ -n $vcs_info_msg_0_ ]] && print -v 'psvar[1]' -Pr -- "$vcs_info_msg_0_" } # You can now use `%1v' to drop the $vcs_info_msg_0_ contents in your prompt; # like this: PS1="%m%(1v.%F{red}%1v%f.)%# " # Episode III: "The justsetitinprecmd way" # This is the way I prefer. When you see it, you may think "Setting that # variable in precmd() each time? What a waste..."; but let me assure you, # you're running vcs_info already, setting one variable is not an issue. # # You're getting the benefit of being able to programmatically setting your # prompt, which is nice especially when you're going to do weird things in # there anyway. Here goes: precmd() { # As always first run the system so everything is setup correctly. vcs_info # And then just set PS1, RPS1 and whatever you want to. This $PS1 # is (as with the other examples above too) just an example of a very # basic single-line prompt. See "man zshmisc" for details on how to # make this less readable. :-) if [[ -z ${vcs_info_msg_0_} ]]; then # Oh hey, nothing from vcs_info, so we got more space. # Let's print a longer part of $PWD... PS1="%5~%# " else # vcs_info found something, that needs space. So a shorter $PWD # makes sense. PS1="%3~${vcs_info_msg_0_}%# " fi } ### check-for-changes just in some places #################################### # Some backends (git and mercurial at the time of writing) can tell you # whether there are local changes in the current repository. While that's # nice, the actions needed to obtain the information can be potentially # expensive. So if you're working on something the size of the linux kernel # or some corporate code monstrosity you may want to think twice about # enabling the `check-for-changes' style unconditionally. # # Zsh's zstyle configuration system let's you do some magic to enable styles # only depending on some code you're running. # # So, what I'm doing is this: I'm keeping my own projects in `~/src/code'. # There are the projects I want the information for most. They are also # a lot smaller than the linux kernel so the information can be retrieved # instantaneously - even on my old laptop at 600MHz. And the following code # enables `check-for-changes' only in that subtree: zstyle -e ':vcs_info:git:*' \ check-for-changes 'estyle-cfc && reply=( true ) || reply=( false )' function estyle-cfc() { local d local -a cfc_dirs cfc_dirs=( ${HOME}/src/code/*(/) ) for d in ${cfc_dirs}; do d=${d%/##} [[ $PWD == $d(|/*) ]] && return 0 done return 1 } ### Hook Examples ############################################################ # A number of examples in this file revolve around the concept of `hooks' # in vcs_info. Hooks are places in vcs_info where you may put in your # own code to achieve something "totally awesome"[tm]. # # Hooks can be confusing. It's hard to keep track of what's going on. # In order to help you with that vcs_info can output some debugging # information when it processes hooks. This will tell you which hooks # are being run and which functions are attempted to run (and if the # functions in question were found or not). # # If you feel like you need to see what's attempted and where, I suggest # you use the following line and see for yourself. zstyle ':vcs_info:*+*:*' debug true # You can just comment it out (or disable it) again when you've seen enough. # Debugging is off by default - of course. zstyle ':vcs_info:*+*:*' debug false # Further down, every example that uses a function named `+vi-*' uses a hook. ### Truncate Long Hashes ### Truncate a long hash to 12 characters (which is usually unique enough) # Use zformat syntax (remember %i is the hash): %12.12i # git: zstyle ':vcs_info:git*' formats "(%s)-[%12.12i %b]-" # hash & branch ### Fetch the full 40-character Mercurial revision id # There is no great way to obtain branch, local rev, and untracked changes in # addition to the full 40-character global rev id with a single invocation of # Mercurial. This hook obtains the full global rev id using xxd(1) (in the # same way the use-simple flag does) while retaining all the other vcs_info # default functionality and information. zstyle ':vcs_info:hg*+set-message:*' hooks hg-fullglobalrev # Output the full 40-char global rev id function +vi-hg-fullglobalrev() { local dirstatefile="${hook_com[base]}/.hg/dirstate" local grevid="$(xxd -p -l 20 < ${dirstatefile})" # Omit %h from your hgrevformat since it will be included below hook_com[revision]="${hook_com[revision]} ${grevid}" } ### Display the existence of files not yet known to VCS ### git: Show marker (T) if there are untracked files in repository # Make sure you have added staged to your 'formats': %c zstyle ':vcs_info:git*+set-message:*' hooks git-untracked +vi-git-untracked(){ if [[ $(git rev-parse --is-inside-work-tree 2> /dev/null) == 'true' ]] && \ git status --porcelain | grep -q '^?? ' 2> /dev/null ; then # This will show the marker if there are any untracked files in repo. # If instead you want to show the marker only if there are untracked # files in $PWD, use: #[[ -n $(git ls-files --others --exclude-standard) ]] ; then hook_com[staged]+='T' fi } ### Compare local changes to remote changes ### git: Show +N/-N when your local branch is ahead-of or behind remote HEAD. # Make sure you have added misc to your 'formats': %m zstyle ':vcs_info:git*+set-message:*' hooks git-st function +vi-git-st() { local ahead behind local -a gitstatus # Exit early in case the worktree is on a detached HEAD git rev-parse ${hook_com[branch]}@{upstream} >/dev/null 2>&1 || return 0 local -a ahead_and_behind=( $(git rev-list --left-right --count HEAD...${hook_com[branch]}@{upstream} 2>/dev/null) ) ahead=${ahead_and_behind[1]} behind=${ahead_and_behind[2]} (( $ahead )) && gitstatus+=( "+${ahead}" ) (( $behind )) && gitstatus+=( "-${behind}" ) hook_com[misc]+=${(j:/:)gitstatus} } ### git: Show remote branch name for remote-tracking branches zstyle ':vcs_info:git*+set-message:*' hooks git-remotebranch function +vi-git-remotebranch() { local remote # Are we on a remote-tracking branch? remote=${$(git rev-parse --verify ${hook_com[branch]}@{upstream} \ --symbolic-full-name 2>/dev/null)/refs\/remotes\/} # The first test will show a tracking branch whenever there is one. The # second test, however, will only show the remote branch's name if it # differs from the local one. if [[ -n ${remote} ]] ; then #if [[ -n ${remote} && ${remote#*/} != ${hook_com[branch]} ]] ; then hook_com[branch]="${hook_com[branch]} [${remote}]" fi } ### Derive hook names dynamically # With the following line: zstyle -e ':vcs_info:git+set-message:*' hooks 'reply=( ${${(k)functions[(I)[+]vi-git-set-message*]}#+vi-} )' # Any function named `+vi-git-set-message-<anything>' would be automatically # registered as a hook. For example: +vi-git-set-message-foo() {} +vi-git-set-message-bar() {} # Both of these functions would be called, even if they are defined after the zstyle is set. ## git: Display pertinent environment variables # If environment variables such as $GIT_DIR, $GIT_WORK_TREE, etc are set in the # environment, they'll be shown in the value of the %m expando. # # Note that the %m expando is not used by default. To see a change, either change # `[misc]' to `[branch]', or set the `formats` style to a value that includes `%m'. zstyle ':vcs_info:git+post-backend:*' hooks git-post-backend-envvars +vi-git-post-backend-envvars() { local param # This uses the ${parameters} special variable (provided by the zsh/parameter # module), in conjunction with the parameter expansion flags ${(k)foo} and # ${(M)foo:#pattern} (documented in "Parameter Expansion" in zshexpn(1)) # and the (R) subscript flag (documented in "Subscript Flags" in zshparam(1)), # to iterate over the names of all environment variables named "GIT_*". Then # it uses the ${(P)foo} parameter expansion flag to show the values of those # parameters. # # The value of ${hook_com[misc]} is substituted for %m in the values of the # 'formats' and 'actionformats' styles. for param in ${(Mk)parameters[(R)*export*]:#GIT_*}; do hook_com[misc]+=";%U${param//'%'/%%}%u=%F{white}${${(P)param}//'%'/%%}%f" done } ### hg: Show marker when the working directory is not on a branch head # This may indicate that running `hg up` will do something # NOTE: the branchheads.cache file is not updated with every Mercurial # operation, so it will sometimes give false positives. Think of this more as a # hint that you might not be on a branch head instead of the final word. zstyle ':vcs_info:hg+set-hgrev-format:*' hooks hg-storerev zstyle ':vcs_info:hg+set-message:*' hooks hg-branchhead # The hash is available in the hgrev-format hook, store a copy of it in the # user_data array so we can access it in the second function function +vi-hg-storerev() { user_data[hash]=${hook_com[hash]} } function +vi-hg-branchhead() { local branchheadsfile i_tiphash i_branchname local -a branchheads local branchheadsfile=${hook_com[base]}/.hg/branchheads.cache # Bail out if any mq patches are applied [[ -s ${hook_com[base]}/.hg/patches/status ]] && return 0 if [[ -r ${branchheadsfile} ]] ; then while read -r i_tiphash i_branchname ; do branchheads+=( $i_tiphash ) done < ${branchheadsfile} if [[ ! ${branchheads[(i)${user_data[hash]}]} -le ${#branchheads} ]] ; then hook_com[revision]="^ ${hook_com[revision]}" fi fi } ### Show information about patch series # This is used with with hg mq, quilt, and git rebases and conflicts. # # All these cases have a notion of a "series of patches/commits" that is being # applied. The following shows the information about the most recent patch to # have been applied: zstyle ':vcs_info:*+gen-applied-string:*' hooks gen-applied-string function +vi-gen-applied-string() { # Separate the patch id from the patch log message. if [[ $1 == *\ * ]]; then local patch_name_or_filename="${1%% *}" local patch_description="${1#* }" else local patch_name_or_filename="$1" local patch_description="" fi # Apply escaping; see `Oddities' in the manual. patch_name_or_filename=${patch_name_or_filename//'%'/%%} patch_description=${patch_description//'%'/%%} # Apply different colouring to the patch description. if [[ -n ${patch_description} ]]; then patch_description="%F{yellow}${patch_description}%f" fi # Re-assemble $1, escaped and coloured. hook_com[applied-string]="${patch_name_or_filename} ${patch_description}" ret=1 } # The value of hook_com[applied-string] is incorporated into the %m expando # (see the 'patch-format' style for details), which is not included in the # 'formats' and 'actionformats' style by default, so to actually use this, # you'll need to add %m (or %Q under quilt in add-on mode) to your 'formats' # and 'actionformats' styles, as in: # # zstyle ':vcs_info:*' actionformats ' (%s)-[%b|%a]%u%c- %m' # zstyle ':vcs_info:*' formats ' (%s)-[%b]%u%c- %m' # # Or you could add it as a new word, as in: # # zstyle ':vcs_info:*' actionformats ' (%s)-[%b|%a]%u%c-' '%m' # zstyle ':vcs_info:*' formats ' (%s)-[%b]%u%c-' '%m' # # In the latter case, you will need to arrange to print ${vcs_info_msg_1_} in # addition to ${vcs_info_msg_0_}; see the top of this file for details. ### Run vcs_info selectively to increase speed in large repos ################ # The following example shows a possible setup for vcs_info which displays # staged and unstaged changes in the vcs_info prompt and prevents running # it too often for speed reasons. # Allow substitutions and expansions in the prompt, necessary for # using a single-quoted $vcs_info_msg_0_ in PS1, RPOMPT (as used here) and # similar. Other ways of using the information are described above. setopt promptsubst # Load vcs_info to display information about version control repositories. autoload -Uz vcs_info # Check the repository for changes so they can be used in %u/%c (see # below). This comes with a speed penalty for bigger repositories. zstyle ':vcs_info:*' check-for-changes true zstyle ':vcs_info:*' get-revision true # Alternatively, the following would set only %c, but is faster: #zstyle ':vcs_info:*' check-for-changes false #zstyle ':vcs_info:*' check-for-staged-changes true # Default to running vcs_info. If possible we prevent running it later for # speed reasons. If set to a non empty value vcs_info is run. FORCE_RUN_VCS_INFO=1 # Only run vcs_info when necessary to speed up the prompt and make using # check-for-changes bearable in bigger repositories. This setup was # inspired by Bart Trojanowski # (http://jukie.net/~bart/blog/pimping-out-zsh-prompt). # # This setup is by no means perfect. It can only detect changes done # through the VCS's commands run by the current shell. If you use your # editor to commit changes to the VCS or if you run them in another shell # this setup won't detect them. To fix this just run "cd ." which causes # vcs_info to run and update the information. If you use aliases to run # the VCS commands update the case check below. zstyle ':vcs_info:*+pre-get-data:*' hooks pre-get-data +vi-pre-get-data() { # Only Git and Mercurial support and need caching. Abort if any other # VCS is used. [[ "$vcs" != git && "$vcs" != hg ]] && return # If the shell just started up or we changed directories (or for other # custom reasons) we must run vcs_info. if [[ -n $FORCE_RUN_VCS_INFO ]]; then FORCE_RUN_VCS_INFO= return fi # If we got to this point, running vcs_info was not forced, so now we # default to not running it and selectively choose when we want to run # it (ret=0 means run it, ret=1 means don't). ret=1 # If a git/hg command was run then run vcs_info as the status might # need to be updated. case "$(fc -ln $(($HISTCMD-1)))" in git*) ret=0 ;; hg*) ret=0 ;; esac } # Call vcs_info as precmd before every prompt. prompt_precmd() { vcs_info } add-zsh-hook precmd prompt_precmd # Must run vcs_info when changing directories. prompt_chpwd() { FORCE_RUN_VCS_INFO=1 } add-zsh-hook chpwd prompt_chpwd # Display the VCS information in the right prompt. The {..:- } is a # workaround for Zsh below 4.3.9. RPROMPT='${vcs_info_msg_0_:- }' ### Quilt support ############################################################ # Vcs_info does its best to support the patch management system quilt # <http://savannah.nongnu.org/projects/quilt>. The information gathered by # the quilt support always (and I'm saying always, because there are two # ways quilt support can be active - see "man zshcontrib" for details) # ends up in the `%Q' replacement in formats. # # Quilt support is also disabled by default. To turn its `addon' mode # on for all backends, do: zstyle ':vcs_info:*' use-quilt true # Then use `%Q' somewhere in the `formats' and `actionformats' styles: zstyle ':vcs_info:*' formats " (%s)-[%b%Q]-" zstyle ':vcs_info:*' actionformats " (%s)-[%b%Q|%a]-" # In the quilt support code, the zstyle context changes a little, it's now: # :vcs_info:<vcs>.quilt-<quiltmode>:*:* # "<vcs>" is the version-control-system string and "<quiltmode>" is either # `addon' or `standalone'. So, if you'd use quilt on top of CVS, the # context becomes ":vcs_info:cvs.quilt-addon:*:*". # That's almost all you need to know. Almost. # # Quilt support has a standalone mode. Even though quilt is not really # a version control system, it keeps track of patches. It can work on top # of a real VCS (like subversion or CVS - which is covered by addon mode) # or apply patches to a normal directory tree that's not under version # control. The debian project does this for a large number of packages, # during their automatic build process. # The `use-quilt' style only enables addon-mode, because for standalone # mode we'd have to try to detect whether quilt is "active" in a directory. # You can fine-tune that "detection" using the `quilt-standalone' style. # If the value of that style is a function name, that function is executed # without arguments to determine whether quilt-detection should be attempted. # It's the most powerful way of doing this and we'll give a simple # example later. # First let's assume you want standalone mode to be active only in # /usr/src/debian, ~/src/debian and their subdirectories. That's simple: typeset -a foobar foobar=( /usr/src/debian ~/src/debian ) zstyle ':vcs_info:*' quilt-standalone foobar # As mentioned earlier, using a function in this style is more powerful: function foobar() { # You can do any sort of wicked wizardry here. This example just # checks if we're in "/usr/src/debian" or a subdirectory and if so # enables standalone detection. [[ $PWD == /usr/src/debian(|/*) ]] && return 0 # Returning non-zero means false, which means don't enable the # "detection". return 1 } # In standalone-mode, vcs_info pretends as if quilt actually was a VCS. # Well, kind of. The vcs string is set to '-quilt-.quilt-standalone'. So let's # define a format just for that mode: zstyle ':vcs_info:-quilt-.quilt-standalone:*' formats " [%s%Q]-" # As with other format insertions, you got total control over what is being # inserted. The `%Q' insertion is controlled by the `quiltformat' and # `quilt-nopatch-format' styles. # quiltformat (default: "%p (%n applied)") # The `%p' replacement tells you which patches are applied. `%n' tells you # How many patches are applied. `%u' and `%N' do the same for unapplied patches. # # Now you might say, that's way too much. That'll eat up my entire screen if I # all my 1002 patches applied. Well, true. # By default, `%p' contains the top-most applied patch. `%u' says contains the # number of unapplied patches and is therefore the same as `%c'. # There are two hooks you can use to setup what these contain. Those would be # `gen-applied-string' and `gen-unapplied-string'. We'll go with the default # here... ...no need to go into every insane detail. zstyle ':vcs_info:*' patch-format '#%p [%n|%c]' # quilt-nopatch-format (default: "no patch applied") zstyle ':vcs_info:*' nopatch-format '#cleeaaaaan!1!!' # To retrieve information about unapplied patches, vcs_info invokes `quilt' # itself. Even though that's pretty quick, it's not needed for the default # behaviour. If we want to have `%c' and `%u' to contain meaningful data, # we have to enable retrieval of unapplied data: zstyle ':vcs_info:*' get-unapplied true # With quilt, the location of its patches are configurable. It's either # $QUILT_PATCHES or `patches' if that's unset. Let's assume we're a debian # developer and want $QUILT_PATCHES to always be `debian/patches' in stand- # alone mode: zstyle ':vcs_info:-quilt-.quilt-standalone:*:*' quilt-patch-dir debian/patches # Since we're a debian developer, we also have some packages of our own, # and so we want addon mode to also use a $QUILT_PATCHES value of # `debian/patches' in some directories. In the other directories we never # want the default `patches' though but a dedicated place for them. # Say `~/patches/<repository-name>'. # # First of all, even without any configuration, vcs_info will do the right # thing most of the time. Whenever quilt has already run in a directory, # vcs_info will figure out whether that directory uses `patches' or # `debian/patches' by interrogating metadata in the `.pc/' subdirectory, # which quilt creates. To make vcs_info find the patches dir correctly even # when the `.pc/' directory doesn't exist, read on. # # We'll use some evaluated-style magic to achieve that: zstyle -e ':vcs_info:*.quilt-addon:*:*' quilt-patch-dir 'my-patches-func' # That runs something called `my-patches-func', and the value of $reply is # used as the value for the `quilt-patch-dir' style. We'll define the thing # as a function - as the name suggests: function my-patches-func() { local p # As the tidy debian developer we are, we're keeping our packages # in VCSs and they are located in one place `~/src/mypkgs/' if [[ $PWD == ${HOME}/src/mypkgs(|/*) ]]; then reply=( debian/patches ) return 0 fi # Now the part about the dedicated directory is a little trickier. # The variable in question here is `$context', which is the zstyle # context used for lookups. Its last component is the repository-root-name, # or ${rrn} for short. If you're in # /usr/src/zsh/Functions # and the repository being # /usr/src/zsh # then the value of `$rrn' would be `zsh'. local rrn=${context##*:} # Now, in case the variable is empty (it shouldn't at this point, but you # never know), let's drop back to quilt's default value, "patches". if [[ -z ${rrn} ]]; then reply=( patches ) return 0 fi # If we're here, there's something in $rrn, so: p="${HOME}/patches/${rrn}" if [[ ! -d $p ]]; then # ...and while we're at it, make sure it exists... mkdir -p "$p" fi reply=( $p ) } # And finally, let's use the `post-quilt' hook to let vcs_info help us # with setting the $QUILT_PATCHES variable. Since vcs_info already knows # which $QUILT_PATCHES value is correct, it should just export that variable # for us. No need to configure something twice when it can work # automatically. :-) # Register the hook: zstyle ':vcs_info:*+post-quilt:*:*' hooks set-quilt-patches # Define the corresponding function: function +vi-set-quilt-patches() { # The `post-quilt' hook functions are called with three arguments: # $1 the mode (`addon' vs. `standalone'). # $2 the path-name of the detected patches directory. # $3 the path-name of the `.pc' directory (or "-nopc-" if it # could not be found). # So, what we're after is in $2 already, which makes this function # rather trivial: export QUILT_PATCHES="$2" return 0 } # This would take care of all the dedicated-patches-directory-in-${HOME} # from earlier examples, too. # Finally, the "Show information about patch series" example above this section # may also be useful. ### Using vcs_info from CVS ################################################## # You've decided you desperately need a newer feature of vcs_info than # there is in your installed version of zsh. That's possible, but be aware # that you are choosing not only the newest features but potentially also # the newest bugs of vcs_info. Also note, that vcs_info from CVS *may* rely # on features of zsh that are only available in a newer version than you # got installed on your system. # # So, now that the warnings are out of the way - let's cut to the chase: # First you'll need to decide where to put the files from CVS. Many people # keep a directory for personal function files such as `~/.zfuncs' or # similar. That's what we'll use here. # # Step one: "get the thing from CVS" # % mkdir -p ~/.zfuncs # % cd ~/.zfuncs # % cvs -z3 -d:pserver:anonymous@zsh.cvs.sourceforge.net:/cvsroot/zsh \ # co -d VCS_Info -PA zsh/Functions/VCS_Info # # There, now you got a `~/.zfuncs/VCS_Info' directory that has all the files # you need. Whenever you feel like updating the checkout, you can do: # % cd ~/.zfuncs/VCS_Info; cvs up; cd - # # Step two: "Tell zsh to use the checkout" # Zsh looks for function files in the directories listed in $fpath. If # you're already using `~/.zfuncs' you probably have something like this # in your setup: fpath=( ~/.zfuncs $fpath ) # Note, that the private directory is added in *front* of the default # value, so that files from that directory supersede the ones from system # directories. To add the VCS_Info subtree (excluding the CVS directories) # in front, change that line to this: fpath=( ~/.zfuncs ~/.zfuncs/VCS_Info/**/*~*/(CVS)#(/) $fpath ) # The weirdly looking pattern requires the `extended_glob' option to be # active, so make sure it is. # # Step three: "Restart Z shell" # A simple # % exec zsh # gets you there. You should be all set now. Have fun.