Rudy Rigot edited this page May 6, 2016 · 18 revisions

Spend a lot of time cd-ing around a complex directory tree?

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.


How come z .. doesn’t work like cd ..?

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.

What if i’m searching for something with a single-dash -, like a directory named-like-this?

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.

How do i “source” something? Why?

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.

It’s not working on OSX. I put stuff but nothing happens?

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

It’s not working on Windows/cygwin. Sourcing z.sh gives weird errors

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.

Tab completion isn’t working in zsh

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).

Read about Frecency: