z.lua - A Faster Way Of Changing Directories (cd Command That Learns As You Use It)

z.lua is a new tool that helps navigate your filesystem faster from the command line, tracking your most used directories based on "frecency".

At first, the tool learns your most frequently used directories, and then uses a "frecency" (based on how recently and how frequently a directory was accessed) based algorithm to rank directories, making it easy to navigate to certain directories by only typing a few letters of their path. Don't expect z.lua to work right away, it will take a bit of time for it to create a database of frequent and recent directories.

While there are other similar tool out there, the developer claims z.lua is a lot faster. For example, z.lua is supposed to be 10 times faster than fasd and autojump, and 3 times faster than z.sh.

What's more, z.lua includes two matching algorithms. The default matching algorithm is similar to the one used by z.sh, in which the paths must match all regexes in order. There's also an enhanced matching algorithm, in which queries must match the path in order, like the default method, and the last query must match the last segment of the path; if no match is found, the default matching is used. Both are explained in detail on the z.lua project page.

z.lua features:

  • 10x times faster than fasd and autojump, 3x times faster than z.sh.
  • Available for: bash, zsh, dash, sh, ash, ksh, busybox, Fish Shell, Power Shell and Windows cmd.
  • 2 directory matching algorithms.
  • Allow updating database only if $PWD changed with $_ZL_ADD_ONCE set to 1.
  • Interactive selection enables you to choose where to go before cd (when there are multiple matches found, using z -i displays a list of matching directories)
  • Integrated with fzf (optional) for interactive selection and completion.
  • Quickly go back to a parent directory instead of typing cd ../../..
  • Similar experience in different shells and operating systems.
  • Compatible with Lua 5.1, 5.2 and 5.3+

z.lua also comes with some options which let you change the command, exclude directories from matching, and it can even import data from z.sh or autojump.

z.lua example


Example 1.

Let's say you have a long path like /a/b/c/foo/bar, and you want to navigate to it from the command line. With z.sh, you only have to type this to navigate directly to the bar directory:

z foo bar

This matches foo/bar, but not bar/foo!

Example 2.

Let's take a look at a real-world example from my computer. I have this path on my system: /home/logix/Stuff/Unity3d/unity2d_platformer/Assets/Art

The path is very long, and it takes a while to navigate to it using a terminal, even with TAB completion.

After I've navigated to this folder once using a terminal (so z.lua can track it), I can now use z.lua to go straight to the Art folder:

z art

The command is very short because I don't have any other Art directories to which I've navigated recently (in fact it's the only Art folder on my system). If I'd have multiple folders with the same name, I could type the following to navigate to this particular folder:

z assets art

You can see a lot more usage examples on the z.lua project page, including how to cd to the highest ranker dir, the most recently accessed dir, list matches instead of cd, and more.

Install z.lua


To use z.lua you'll need to install Lua:

  • Debian, Ubuntu, Linux Mint, elementary OS, and other Debian or Ubuntu-based Linux distributions:
sudo apt install lua5.2

  • Fedora:
sudo dnf install lua

On other Linux distributions you should find Lua in the repositories.

Now you can download the latest z.lua release, extract it, and use the installation instructions to install it for your shell (Bash, Zsh, Fish, Power Shell, Windows cmd and so on).

For example, if you're using Bash, extract the z.lua release archive in a ~/.z.lua folder on your system, then add this to your ~/.bashrc file:

  • to use the default matching method:
eval "$(lua ~/.z.lua/z.lua --init bash)"

  • to use the enhanced matching algorithm:
eval "$(lua ~/.z.lua/z.lua --init bash enhanced once)"

After saving the changes you've made to ~/.bashrc, open a new terminal or source it:

source ~/.bashrc

Now you're ready to use z.lua, though remember that it must create a database to figure out to which directory you want to navigate to.