z keeps track of where you’ve been, and how much time you spend there. Source it into your .bashrc, and then you can say z foo to jump to the most used directory that has the substring (actually regex) foo in it, or z foo bar for the directory that has both foo and bar …

It tab completes out of its file ($HOME/.z), and tries a case sensitive match first, then tries to match without case sensitivity.

z by itself (or z -l) displays the current list of directories being remembered.

z is not intended as a substitute for the cd command. You should still cd everywhere as you normally would. When you want to jump somewhere you have been, then type z substring to jump a directory in your often used list.

Like many other shell programs, passing an argument of -- to z will force all further arguments to be treated as search terms. So z -- -h will match directories that contain -h.

Short answer: instead of running the script as z.sh you type source z.sh or . z.sh in a shell, or to make it available all the time, put a command in your .bashrc that sources it, or just paste the contents of z.sh directly into your .bashrc.

Long answer: sourcing is like importing. When you run a script in a shell, it creates a subshell, runs your script, and returns to your current shell. If you cd in that subshell, it won’t matter to your current shell, because when your script is done running, it exits, and comes back to where you (still) are in your current shell. What we want in this case is to have the function and commands in our script defined in our current shell. Sourcing – rather than executing – the file does exactly that.

By default, OSX doesn’t source ~/.bashrc. It will, however, source ~/.bash_profile. One solution is to follow the install instruction, but use ~/.bash_profile instead of ~/.bashrc. Another solution, which the author uses, is to source ~/.bashrc from ~/.bash_profile:

~$ cat .bash_profile
[ -f "$HOME/.bashrc" ] && . $HOME/.bashrc
~$

After sourcing z.sh, I get the following errors:

$ source ~/bin/z.sh
bash: $'\r': command not found
bash: $'\r': command not found
ERROR: z.sh's datafile (/home/THLHE/.z) is a directory.
bash: $'}\r': command not found
bash: $'\r': command not found
bash: /home/THLHE/bin/z.sh: line 30: syntax error near unexpected token `$'{\r''
'ash: /home/THLHE/bin/z.sh: line 30: `_z() {

You probably cloned the z.sh repository with git, which then used Windows-style line endings (\r\n). Download the script directly with a web browser instead.

Zsh has a lot of completion configuration options, some of which don’t play well with z. Before opening an issue, please try with your ~/.zshrc moved out of the way, if it works then, you can look at your configuration a bit more. In particular, the completealiases option is known to break tab completion (see issue #72).

Frecency