Home

Awesome

Zsh-z

MIT License Zsh version 4.3.11 and higher GitHub stars

Zsh-z demo

Zsh-z is a command-line tool that allows you to jump quickly to directories that you have visited frequently or recently -- but most often a combination of the two (a concept known as "frecency"). It works by keeping track of when you go to directories and how much time you spend in them. Based on this data, it predicts where you want to go when you type a partial string. For example, z src might take you to ~/src/zsh. z zsh might also get you there, and z c/z might prove to be even more specific -- it all depends on your habits and how long you have been using Zsh-z to build up a database. After using Zsh-z for a little while, you will get to where you want to be by typing considerably less than you would need to if you were using cd.

Zsh-z is a native Zsh port of rupa/z, a tool written for bash and Zsh that uses embedded awk scripts to do the heavy lifting. rupa/z was my most used command-line tool for a couple of years. I decided to translate it, awk parts and all, into pure Zsh script, to see if by eliminating calls to external tools (awk, sort, date, sed, mv, rm, and chown) and reducing forking through subshells I could make it faster. The performance increase is impressive, particularly on systems where forking is slow, such as Cygwin, MSYS2, and WSL. I have found that in those environments, switching directories using Zsh-z can be over 100% faster than it is using rupa/z.

There is also a significant stability improvement. Race conditions have always been a problem with rupa/z, and users of that utility occasionally lose their ~/.z databases. By having Zsh-z only use Zsh (rupa/z uses a hybrid shell code standard that works on bash as well), I have been able to implement a zsh/system-based file-locking mechanism similar to the one @mafredri once proposed for rupa/z. It is now nearly impossible to crash the database.

There are other, smaller improvements which I document below in Improvements and Fixes. For instance, tab completions are now sorted by frecency by default rather than alphabetically (the latter behavior can be restored if you like it -- see below).

Zsh-z is a drop-in replacement for rupa/z and will, by default, use the same database (~/.z, or whatever database file you specify), so you can go on using rupa/z when you launch bash.

Table of Contents

News

<details> <summary>Here are the latest features and updates.</summary> </details>

Installation

General observations

This plugin can be installed simply by putting the various files in a directory together and by sourcing zsh-z.plugin.zsh in your .zshrc:

source /path/to/zsh-z.plugin.zsh

For tab completion to work, _zshz must be in the same directory as zsh-z.plugin.zsh, and you will want to have loaded compinit. The frameworks handle this themselves. If you are not using a framework, put

autoload -U compinit; compinit

in your .zshrc somewhere below where you source zsh-z.plugin.zsh.

If you add

zstyle ':completion:*' menu select

to your .zshrc, your completion menus will look very nice. This zstyle invocation should work with any of the frameworks below as well.

For antigen users

Add the line

antigen bundle agkozak/zsh-z

to your .zshrc, somewhere above the line that says antigen apply.

For Oh My Zsh users

Zsh-z is now included as part of Oh My Zsh! As long as you are using an up-to-date installation of Oh My Zsh, you can activate Zsh-z simply by adding z to your plugins array in your .zshrc, e.g.,

plugins=( git z )

It is as simple as that.

If, however, you prefer always to use the latest version of Zsh-z from the agkozak/zsh-z repo, you may install it thus:

git clone https://github.com/agkozak/zsh-z ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-z

and activate it by adding zsh-z to the line of your .zshrc that specifies plugins=(), e.g., plugins=( git zsh-z ).

For prezto users

Execute the following command:

git clone https://github.com/agkozak/zsh-z.git ~/.zprezto-contrib/zsh-z

Then edit your ~/.zpreztorc file. Make sure the line that says

zstyle ':prezto:load' pmodule-dirs $HOME/.zprezto-contrib

is uncommented. Then find the section that specifies which modules are to be loaded; it should look something like this:

zstyle ':prezto:load' pmodule \
    'environment' \
    'terminal' \
    'editor' \
    'history' \
    'directory' \
    'spectrum' \
    'utility' \
    'completion' \
    'prompt'

Add a backslash to the end of the last line add 'zsh-z' to the list, e.g.,

zstyle ':prezto:load' pmodule \
    'environment' \
    'terminal' \
    'editor' \
    'history' \
    'directory' \
    'spectrum' \
    'utility' \
    'completion' \
    'prompt' \
    'zsh-z'

Then relaunch zsh.

For zcomet users

Simply add

zcomet load agkozak/zsh-z

to your .zshrc (below where you source zcomet.zsh and above where you run zcomet compinit).

For zgen users

Add the line

zgen load agkozak/zsh-z

somewhere above the line that says zgen save. Then run

zgen reset
zsh

to refresh your init script.

For Zim

Add the following line to your .zimrc:

zmodule https://github.com/agkozak/zsh-z

Then run

zimfw install

and restart your shell.

For Zinit users

Add the line

zinit load agkozak/zsh-z

to your .zshrc.

Zsh-z supports zinit's unload feature; just run zinit unload agkozak/zsh-z to restore the shell to its state before Zsh-z was loaded.

For Znap users

Add the line

znap source agkozak/zsh-z

somewhere below the line where you source Znap itself.

For zplug users

Add the line

zplug "agkozak/zsh-z"

somewhere above the line that says zplug load. Then run

zplug install
zplug load

to install Zsh-z.

Command Line Options

Settings

Zsh-z has environment variables (they all begin with ZSHZ_) that change its behavior if you set them. You can also keep your old ones if you have been using rupa/z (whose environment variables begin with _Z_).

Case sensitivity

The default behavior of Zsh-z is to try to find a case-sensitive match. If there is none, then Zsh-z tries to find a case-insensitive match.

Some users prefer simple case-insensitivity; this behavior can be enabled by setting

ZSHZ_CASE=ignore

If you like Vim's smartcase setting, where lowercase patterns are case-insensitive while patterns with any uppercase characters are treated case-sensitively, try setting

ZSHZ_CASE=smart

ZSHZ_UNCOMMON

A common complaint about the default behavior of rupa/z and Zsh-z involves "common prefixes." If you type z code and the best matches, in increasing order, are

/home/me/code/foo
/home/me/code/bar
/home/me/code/bat

Zsh-z will see that all possible matches share a common prefix and will send you to that directory -- /home/me/code -- which is often a desirable result. But if the possible matches are

/home/me/.vscode/foo
/home/me/code/foo
/home/me/code/bar
/home/me/code/bat

then there is no common prefix. In this case, z code will simply send you to the highest-ranking match, /home/me/code/bat.

You may enable an alternate, experimental behavior by setting ZSHZ_UNCOMMON=1. If you do that, Zsh-z will not jump to a common prefix, even if one exists. Instead, it chooses the highest-ranking match -- but it drops any subdirectories that do not include the search term. So if you type z bat and /home/me/code/bat is the best match, that is exactly where you will end up. If, however, you had typed z code and the best match was also /home/me/code/bat, you would have ended up in /home/me/code (because code was what you had searched for). This feature is still in development, and feedback is welcome.

Making --add Work for You

Zsh-z internally uses the --add option to add paths to its database. @zachriggle pointed out to me that users might want to use --add themselves, so I have altered it a little to make it more user-friendly.

A good example might involve a directory tree that has Git repositories within it. The working directories could be added to the Zsh-z database as a batch with

for i in $(find $PWD -maxdepth 3 -name .git -type d); do
  z --add ${i:h}
done

(As a Zsh user, I tend to use ** instead of find, but it is good to see how deep your directory trees go before doing that.)

Other Improvements and Fixes

Migrating from Other Tools

Zsh-z's database format is identical to that of rupa/z. You may switch freely between the two tools (I still use rupa/z for bash). fasd also uses that database format, but it stores it by default in ~/.fasd, so you will have to cp ~/.fasd ~/.z if you want to use your old directory history.

If you are coming to Zsh-z (or even to the original rupa/z, for that matter) from autojump, try using my jumpstart-z tool to convert your old database to the Zsh-z format, or simply run

awk -F "\t" '{printf("%s|%0.f|%s\n", $2, $1, '"$(date +%s)"')}' < /path/to/autojump.txt > ~/.z

COMPLETE_ALIASES

z, or any alternative you set up using $ZSH_CMD or $_Z_CMD, is an alias. setopt COMPLETE_ALIASES divorces the tab completion for aliases from the underlying commands they invoke, so if you enable COMPLETE_ALIASES, tab completion for Zsh-z will be broken. You can get it working again, however, by adding under

setopt COMPLETE_ALIASES

the line

compdef _zshz ${ZSHZ_CMD:-${_Z_CMD:-z}}

That will re-bind z or the command of your choice to the underlying Zsh-z function.

Known Bug

It is possible to run a completion on a string with spaces in it, e.g., z us bi<TAB> might take you to /usr/local/bin. This works, but as things stand, after the completion the command line reads

z us /usr/local/bin.

You get where you want to go, but the detritus on the command line is annoying. This is also a problem in rupa/z, but I am keen on eventually eliminating this glitch. Advice is welcome.