yazpt = yet another zsh prompt theme

Yazpt is a clean, fast, good-looking zsh prompt theme that thoughtfully incorporates Git/Subversion/TFVC status info, integrates with popular plugin managers like Oh My Zsh, and is straightforward to customize and extend.

[ Features • Supported/Tested Environments • Installing • Enabling Subversion/TFVC • Customizing ]

Git	Subversion	TFVC

Yazpt's appearance can be easily changed by loading one of its presets:

dense preset	elementary preset	jakshin preset

sapphire preset	spearmint preset	yolo preset

Features

• It's fast. It's faster than any prompt theme which relies on vcs_info, and faster than nearly all prompt themes which don't use async approaches for obtaining and displaying VCS status.

  Yazpt also allows you to configure lists of path prefixes in which you expect to find Git repos, Subversion working copies, and/or Team Foundation Version Control local workspaces - if you've done so, then while working in any path which isn't in one or more of those lists, it skips checking for Git/Subversion/TFVC status, improving performance even further. If you don't happen to use one or more of the supported VCSs, you can also entirely disable yazpt's use of any of them.

• It's as configurable as you want it to be. Yazpt uses about three dozen environment variables to tweak its appearance and behavior. If that sounds like too much to bother with, it also comes with a handful of "presets", i.e. preconfigured settings for the environment variables, in a variety of styles. Or if, on the other hand, you really want to dig in and customize it, it's straightforward to add new prompt segments, or override the default implementations of existing prompt segments, using zsh functions. Either way, the details are all carefully documented to help you jump right in.

• It lets you do your own thing with $PS1 and $RPS1. Yazpt thinks of itself as an add-on or power-up, not a replacement, for zsh's built-in prompt logic, so if you've already spent time pimping out your $PS1 or $RPS1, there's no need to throw that work away - you can copy your current $PS1 straight into $YAZPT_LAYOUT (and/or $RPS1 into $YAZPT_RLAYOUT), and then add any yazpt-specific segments you'd like.

• It's secure. A surprising number of prompt themes will execute arbitrary shell code if you browse an unsafe repo. Others fail to escape the info they show in ways that lead to corrupted display, e.g. allowing zsh to interpret percent escape sequences or exclamation marks in either the current directory's path or a VCS branch name. Yazpt tries hard to avoid those mistakes, and works properly regardless of your preferences about zsh settings like prompt_subst and prompt_bang.

• It doesn't require a patched font. Because it uses only standard Unicode characters, yazpt works fine with most standard terminal fonts. You don't need a patched one, like from Nerd Fonts or Powerline Fonts - but of course if you use one of those fonts in your terminal, you can configure yazpt to use its special glyphs.

• It incorporates Git info thoughtfully. Rather than try to display every detail about the Git status in the prompt, like many prompt themes do, and which has always seemed a bit visually busy to me, yazpt tries to boil it all down to a few key bits of info: the current branch, whether a significant activity is in progress (like merging or rebasing), and one of 3 meaningful, action-oriented statuses:

  • The working tree is dirty (with untracked files, and/or staged or unstaged changes),
  • The local branch has different commits than its remote branch, or
  • Both the working tree and branch are clean, i.e. neither of the above is true.

  There are a couple of other statuses that can be shown in less-common situations; in any case, if you don't know or remember what one of the status characters means, you can just run the explainer function, yazpt_explain_git, for full details.

  Yazpt goes out of its way to make its Git support seamless, e.g. by showing correct Git status info even when you're browsing in the .git directory, which most other prompts don't bother to do.

  Incidentally, yazpt supports bare repos, linked worktrees, and even bare repos' linked worktrees, more completely and correctly than any other prompt theme I've tried.

• It incorporates Subversion info thoughtfully, too. There are a few cases where I still need to use Subversion, and I've generally found other prompt themes' support for it a bit lacking. The biggest gap is that although Subversion thinks of status as a per-directory concept, in all of my SVN usage patterns, it would be more convenient and helpful to see status across my whole working copy, like I'm used to while using Git.

  In general, what I want to know while using Subversion in a terminal is:

  • Which branch I have checked out (usually trunk, but occasionally something else),
  • Whether my last svn update resulted in a conflict that I haven't resolved yet,
  • Whether I have any files locked, anywhere in my working copy, and
  • Whether my working copy is dirty anywhere, i.e. has new unversioned files/directories, or uncommitted file/directory/property changes, in any directory.

  So that's exactly what yazpt shows - even, unlike many other prompt themes, while the current directory is ignored or unversioned, including in the .svn directory.

  Yazpt also has an explainer function for its Subversion statuses - just run yazpt_explain_svn for a list of all possible Subversion statuses and their meanings.

  Note that yazpt's Subversion support is disabled by default, and needs to be enabled.

• It incorporates Team Foundation Version Control info. While I'd probably be a bit happier if TFVC went the way of VSS, the world doesn't always work exactly how I'd like. 😉

  When I use TFVC, it's usually in Visual Studio - and I think I'm normal in that regard - so only lightweight support for TFVC at a prompt seems warranted:

  • Some basic context, i.e. the workspace's server path,
  • Whether the workspace is dirty at all, i.e. has any pending additions/modifications/deletions, and
  • Whether I have any items locked.

  Command-line tools for TFVC exist - a TF.exe ships with Visual Studio for Windows, and on other platforms there's a CLI tool called TEE-CLC - but they run far too slowly to be used while generating a prompt, so instead yazpt parses a couple of TFVC's binary data files itself (properties.tf1 and pendingchanges.tf1).

  The yazpt_explain_tfvc explainer function shows the details.

  Note that yazpt's TFVC support is disabled by default, and needs to be enabled.

  •

Supported/Tested Environments

Yazpt's code logic should work just about anywhere zsh 5.1+ itself does, and with any semi-recent version of the Git and Subversion CLIs, but how well its Unicode VCS status characters get rendered can vary a bit across environments; a bit of tinkering usually fixes things up nicely, or you can load the elementary preset, which only uses ASCII characters.

macOS

Yazpt works hassle-free on all macOS versions since High Sierra, in Apple Terminal (with "Antialias text" turned on), iTerm, and Tabby. It works equally well on Apple's and Homebrew's versions of zsh, git and svn. It's rendered nicely in all of the preinstalled fixed width fonts, plus Bitstream Vera Sans Mono, Fira Code, Meslo, and Source Code Pro.

Windows

Yazpt also works without fuss in Windows Terminal on Windows 10 and Windows 11, whether it's running on Windows Subsystem for Linux (WSL), Cygwin or MSYS2.

It also works in various other terminals, including Mintty, Tabby, MobaXterm, and ConEmu, and on Windows 7 and 8, but a little bit of tinkering is needed for good results -- see the tips for using yazpt on Windows for details.

Haiku

Yazpt works in Haiku R1/beta3's Terminal application, after these steps are taken:

• Install zsh and the DejaVu fonts, either in HaikuDepot, or with pkgman install zsh dejavu
• Configure Terminal to use the DejaVu Sans Mono font

You'll also want to switch Terminal's color theme from the default to one with a dark background.

If you'd like for Terminal to run zsh every time you open a window or tab, rather than bash, create ~/config/settings/bash_profile with these contents:

if [[ $- =~ i && -x /bin/zsh ]]; then
	exec /bin/zsh
fi

Linux

Yazpt works well, with little or no special attention, in many popular distros:

• CentOS 8.3, CentOS Stream 8 and 9, installed as a "server with GUI"
• Debian 10.9 and 11.x, installed with defaults ("Debian desktop environment")
• Kali Linux 2021.1 and newer
• KDE neon
• Kubuntu 20.04 and newer
• Linux Mint 20.1 and newer (Cinnamon, MATE or XFCE)
• openSUSE Leap 15.3 and openSUSE Tumbleweed, running KDE Plasma 5
• Pop!_OS 20.04 and newer
• Solus Budgie 4.3
• Solus GNOME 4.3
• Solus MATE 4.3
• Ubuntu Desktop 20.04 and newer
• Ubuntu MATE 20.04 and newer
• Zorin OS 16.1

It also works well in lots of other distros, after making some minor tweaks to settings and/or installing a font or two. See the tips for using yazpt on GNU/Linux for details.

FreeBSD

I don't use FreeBSD much, but just for kicks I tried yazpt out on a few of its derivatives. It works well after making minor adjustments to settings and/or installing a font; see the tips for using yazpt on FreeBSD derivatives for details.

•

Installing

Yazpt can be installed in a variety of ways, with popular zsh frameworks or completely on its own.

Without a framework

Yazpt doesn't require a framework - to start using it, you can just source yazpt.zsh-theme, on demand or in your .zshrc file. To install, clone the git repo to a location of your choice:

git clone https://github.com/jakshin/yazpt ~/.yazpt

Then source the theme file (in your .zshrc to apply it in all terminal sessions), and optionally load a preset and/or tweak some settings:

source ~/.yazpt/yazpt.zsh-theme

# Optionally, and for example
yazpt_load_preset dense  # Run yazpt_list_presets to see available choices
YAZPT_CWD_COLOR=70       # Type 'YAZPT_' and press tab to see all settings

With zsh's prompt theme system

Yazpt integrates with zsh's native "promptinit" prompt theme system. To install, clone the git repo to a location of your choice, and symlink prompt_yazpt_setup into a directory in your $fpath; running install-resources.zsh is the easiest way:

git clone https://github.com/jakshin/yazpt ~/.yazpt  # Or wherever you'd like
~/.yazpt/resources/install-resources.zsh

To begin using yazpt:

autoload -U promptinit && promptinit  # Usually in .zshrc
prompt yazpt  # You can pass a preset's name if you want, e.g. `prompt yazpt spearmint`

With Oh My Zsh

To install, clone the git repo, and create a symlink for Oh My Zsh to find:

git clone https://github.com/jakshin/yazpt $ZSH_CUSTOM/themes/yazpt
ln -sv $ZSH_CUSTOM/themes/yazpt/yazpt.zsh-theme $ZSH_CUSTOM/themes/yazpt.zsh-theme

Then, in your .zshrc, before the source $ZSH/oh-my-zsh.sh line:

ZSH_THEME="yazpt"

If you'd like to load a preset and/or tweak some settings, put those lines in your .zshrc in the "User configuration" section (after the source $ZSH/oh-my-zsh.sh line):

# Optionally, and for example
yazpt_load_preset jakshin
YAZPT_CWD_COLOR=14

With Prezto

If you've already installed yazpt for zsh's prompt theme system, it'll Just Work with Prezto as well. You don't even need to enable Prezto's Git module.

Otherwise, to install yazpt into Prezto, clone the git repo to a location of your choice, and symlink prompt_yazpt_setup into your .zprezto/modules/prompt/functions directory:

git clone https://github.com/jakshin/yazpt ~/.yazpt  # Or wherever you'd like

target_path="${ZDOTDIR:-$HOME}/.zprezto/modules/prompt/functions"
ln -sv ~/.yazpt/functions/prompt_yazpt_setup $target_path/prompt_yazpt_setup

To use yazpt on demand, run prompt yazpt, optionally with a preset, e.g. prompt yazpt sapphire. To make it your default prompt, put this in the "Prompt" section of your ~/.zpreztorc:

zstyle ':prezto:module:prompt' theme 'yazpt'
# Or with a preset: zstyle ':prezto:module:prompt' theme 'yazpt' 'sapphire'

To tweak yazpt's settings further, add to the bottom of your .zshrc, below the "Customize to your needs" line:

# Optionally, and for example
yazpt_load_preset sapphire
YAZPT_GIT_HIDE_IN_BARE_REPO=true

If you explicitly configure Prezto's pwd-length or show-return-val settings, yazpt will respect those settings while running under Prezto - but you do need to configure them explicitly, rather than relying on Prezto's defaults for those settings, as yazpt doesn't know or care about Prezto's defaults. You'll also still need an <exit> somewhere in your $YAZPT_LAYOUT or $YAZPT_RLAYOUT for setting show-return-val to yes to work.

# Optionally, and for example
zstyle ':prezto:module:prompt' pwd-length 'short'
zstyle ':prezto:module:prompt' show-return-val 'no'

With Zinit

To try the prompt out under Zinit (formerly named Zplugin), run zinit load jakshin/yazpt. To use the prompt in all terminal sessions, just add that line to your .zshrc, then tweak any settings you'd like:

zinit load jakshin/yazpt
yazpt_load_preset yolo  # Optionally, and for example

Or load it asynchronously:

PS1="$(pwd) > "
zinit ice wait'!0' atload'yazpt_load_preset yolo;yazpt_precmd' nocd
zinit light jakshin/yazpt

Yazpt implements an unload function as specified in the Zdharma Zsh Plugin Standard, so you can unload it by calling zinit unload jakshin/yazpt.

•

Enabling Subversion and/or Team Foundation Version Control

By default, yazpt disables its support for Subversion and Team Foundation Version Control. To enable either or both of those VCSs in the prompt, you'll need to adjust the $YAZPT_VCS_ORDER - a good place to do this is right after you load yazpt in your .zshrc. For example, if you mostly use Git, but occasionally work in Subversion and TFVC repos, you can use this setting:

YAZPT_VCS_ORDER=(git svn tfvc)

In order to prevent performance from dropping with the additional VCSs enabled, you'll probably also want to configure yazpt's path prefix list for each VCS, so it only spends time trying to gather VCS status when it needs to. For example, on Windows with Cygwin, something like this might work well:

user_profile_path="$(cygpath "$USERPROFILE")"
YAZPT_GIT_PATHS=("$user_profile_path/Documents/Visual Studio 2019/Projects/" ~/.yazpt)
YAZPT_SVN_PATHS=("$user_profile_path/Documents/Code/")
YAZPT_TFVC_PATHS=("$user_profile_path/Source/Workspaces/")

Note that while yazpt knows when the current directory is ignored by Git or Subversion, and uses a different color when displaying the VCS context, it doesn't know this for TFVC -- if you cd into an ignored directory in a TFVC local workspace, the VCS status will still be displayed in the default color. Yazpt does know enough about whether files/directories are ignored by TFVC to correctly display the local workspace's clean/dirty state, though.

Also, for the TFVC prompt segment to properly display non-ASCII characters in branch names, the iconv command line tool must be available. It's usually installed by default, but not on Cygwin, where the libiconv package must be installed in order to get it.

Finally, when using TFVC on Windows, with the workspace open in Visual Studio, any changes in the workspace get noticed immediately, whether they're made through Visual Studio or otherwise, and TFVC updates its metadata in the $tf directory right away. The same is true when making changes via the tf CLI, whether VS is running or not. But otherwise, like while changing files using general command-line utilities without Visual Studio running, TFVC won't notice changes until you kick it a little - by, say, running tf info or tf status. I hope to improve on this situation eventually.

•

Customizing

Yazpt is quite customizable, with options ranging from very simple (loading a preset) to somewhat complex (implementing a custom segment). Read on for details.