VCPROMPT(1)

📦 version 1.3.0-unstable-2020-12, in nixos 26.05, nixpkgs unstable

💅 VCPROMPT(1) — the vcprompt girlies' guide 💅

okay so bestie, this is the manual page for vcprompt — a User Commands classic, and literally the moment your terminal prompt stops being boring 💖 Sit down, grab a strawberry drink 🍓, and let's get into it.

✨ NAME ✨

vcprompt — version control information in your prompt 🎀

🦋 SYNOPSIS 🦋

vcprompt [-h] [-d] [-t timeout_ms] [-f format]

🌸 DESCRIPTION 🌸

So what it does is: it peeks at the current working directory 👀, figures out which version control system is running the show, and prints a lil short summary to stdout. That's it, that's the whole vibe. But here's the thing — you have to configure your shell to actually run vcprompt for every prompt, and then your prompt gets to include that short summary. Main character energy honestly 👑

By default, vcprompt just shows the name of the version control system plus the current branch, like:

[git:master]
[hg:default]
[svn:trunk]
[cvs:trunk]
[fossil:trunk]

And this is the default because it's useful, implemented, and fast for all supported version control systems 🏃‍♀️💨 no cap.

You can get different information by specifying a format string with the -f option — go look at FORMAT STRINGS below, it's giving menu of possibilities 🍓

If the current directory is not under version control, vcprompt prints nothing and exits. Yeah. Nothing. Silence. The void 💀

💅 OPTIONS 💅

  • -d — Print debug messages to stdout, and always end with a newline. Super useful for understanding why vcprompt does not print what you thought it should print. Do not use this in your shell prompt! 🙈 Like fr fr, don't.
  • -f format — Specify a custom format string (default: "[%n:%b] "). See FORMAT STRINGS below 👇
  • -t timeout — Terminate after timeout milliseconds of attempting to analyze the working dir. Useful if you have slow operations (e.g. %m or %u) in your format string that are tolerable in small working dirs, but not in large ones. The timeout applies to the whole run of vcprompt. If it fires, the entire operation fails: no partial information will be printed. 😭 all or nothing, babe.
  • -F — List features built-in to this vcprompt binary and terminate (mainly for testing).

🌈 FORMAT STRINGS 🌈

vcprompt uses printf-style format strings, where % followed by a single letter expands to some piece of information about the current working dir. The supported format specifiers are:

  • %n — A short all-lowercase name for the version control system managing the working dir: e.g. "git", "hg", "svn", "cvs", "fossil".
  • %b — The name of the current branch.
  • %r — The current revision number, changeset ID, or commit ID.
  • %p — The name of the currently applied patch, if any (Mercurial + MQ only, but it looks like this could easily be supported for git + guilt). iykyk 🧚
  • %u — A single "?" if there are any unknown (untracked) files in the working dir. Slow.
  • %m — A single "+" if there are any uncommitted changes (modified, added, or removed files) in the working dir. Slow.
  • %% — A single "%" character.

Not all version control systems support all format specifiers. For example, CVS has no notion of a single revision identifier, so vcprompt ignores %r in a CVS working dir. See the section on each version control system below for more details 👑

Some format specifiers are slow with most or all supported version control systems. "Slow" generally means that it requires spawning an external command, like "git status" or "fossil info". vcprompt tries hard to avoid spawning external commands, but sometimes it can't be helped 😔 it's doing its best.

🐙 GIT SUPPORT 🐙

vcprompt considers the current directory a git working dir if directory .git exists.

  • %b (branch) is supported by reading .git/HEAD directly. If that file does not refer to a branch (e.g. you have checked out a specified commit), then vcprompt reports the branch as "unknown". 💀 iconic honestly.
  • %r (revision) expands to the first 12 characters of the commit ID of HEAD.
  • %p is not yet implemented.
  • %u is supported by running "git ls-files --others --exclude-standard", so it can be slow in a large working dir.
  • %m is supported by running "git diff --no-ext-diff --quiet --exit-code", so it can be slow in a large working dir.

🧚 MERCURIAL (HG) SUPPORT 🧚

vcprompt considers the current directory a Mercurial (hg) working dir if directory .hg exists.

  • %b (branch) is supported by looking for the current Mercurial bookmark (.hg/bookmarks.current), or the current named branch (.hg/branch) if no bookmark is current.
  • %r (revision) expands to the revision number of the parent of the working dir, or a comma-separated pair of revision numbers if a merge is active (the working dir has two parents). If vcprompt fails to parse some of Mercurial's internal data, it might print a short changeset ID instead of a revision number. If that happens, please report a bug in vcprompt! 🫶
  • %p is implemented by reading MQ internals.
  • %u and %m are implemented by running "hg status", so they can be slow in a large working dir. Mercurial has to work harder to find unknown files than it does to find uncommitted changes, so using %u can be considerably more expensive than just %m. expensive girly 💸

🎀 SUBVERSION (SVN) SUPPORT 🎀

vcprompt considers the current directory a Subversion (svn) working dir if directory .svn exists. vcprompt currently supports Subversion up to version 1.8.

  • %b is supported by parsing the repository URL corresponding to the root of your working copy: if we're in a checkout of .../trunk then branch is "trunk"; if we're in a checkout of .../branches/FOO then branch is "FOO"; otherwise the branch is unknown.
  • %r reports the same as "Last Changed Rev" from "svn info" in the root of your working copy (not necessarily the current directory), i.e. the last revision in which this directory was changed.
  • %p is not implemented (it makes no sense with Subversion).
  • %u and %m are not implemented.

🍓 CVS SUPPORT 🍓

vcprompt considers the current directory a CVS working dir if file CVS/Entries exists.

  • %b (branch) is supported by reading CVS/Tag; if that file does not exist, vcprompt displays the branch as "trunk". vcprompt looks only in the current dir, not in any subdirectories, so it will not detect mixed-branch working dirs. 👀
  • %r is not supported because CVS has no global revision ID.
  • %p is not implemented (it makes no sense with CVS).
  • %u and %m are not supported because CVS has no easy way to get that information.

🦴 FOSSIL SUPPORT 🦴

vcprompt considers the current directory a Fossil working dir if either of the files _FOSSIL_ or .fslckout exist.

All format specifiers depend on running "fossil" commands, so every operation in a Fossil working dir is slow. All format specifiers except %u depend on a single run of "fossil status", so there's no harm in using lots of format specifiers (however, doing so is expensive for other version control systems). slay, batch it 🏃‍♀️

Format specifier %p is not implemented.

Format specifier %u requires running "fossil extra", so has an extra penalty compared to the other format specifiers. extra expensive, bestie 💀

💜 CONFIGURING BASH 💜

Use command substitution to include the output of vcprompt in your prompt. For example, add this to ~/.bashrc:

if [ "$PS1" ]; then
  PS1='\u@\h $(vcprompt -f "[%b]")'
fi

You can of course use all of bash's prompt escape sequences; the above is just an example ✨

🌸 CONFIGURING ZSH 🌸

Enable the PROMPT_SUBST option, and then use command substitution in PROMPT to run vcprompt every time zsh generates the prompt. For example, add this to your ~/.zshrc file:

if [ -n "$PROMPT" ]; then
  setopt prompt_subst
  PROMPT='%n@%m $(vcprompt -f "[%b]")$ '
fi

You can of course use all of zsh's prompt escapes in PROMPT. 💅

🫶 ENVIRONMENT 🫶

  • VCPROMPT_FORMAT — Specifies the default format string (overridden by -f option).

👑 AUTHOR 👑

vcprompt was written by Greg Ward <greg at gerg dot ca>. 🫶 shoutout Greg!!

The latest version is available from either of my public Mercurial repositories:

http://hg.gerg.ca/vcprompt/
http://bitbucket.org/gward/vcprompt/

okay that's the whole thing, no cap 💖 this page is from February 2013 and it's the vcprompt page from User Commands — go forth and make your prompt iconic 🌈✨💅

📦 where this page comes from