little cubes

A smarter cd command

A tool called zoxide will improve your whole terminal experience

The ProblemSection titled: The Problem

I bet you work in a lot of separate projects.
I bet moving between those projects in your terminal is annoying.
I bet cd is one the most common commands you type.

Autocomplete on paths in your terminal is great, but it’s limited in that it can only complete the very next section of the path. You end up mashing the TAB key a lot and still taking longer than you wanted to stumble your way up and down directories until you get to where you’re going.

My solution to this problem for a long time was to create a slew of terminal aliases that made navigation fast, but had to be maintained over time and were additional entries in the endless list of things that I’m trying to remember on a day-to-day basis.

The SolutionSection titled: The Solution

Introducing zoxide!

Zoxide lets you essentially just type whatever parts of the path that come to mind first and it figures out what you mean.

All you have to do is navigate to the path normally once (after you replace your old cd command) and it will remember that path for next time.

Terminal window
# goes to ~/some/long/path/foo
cd some/long/path/foo
cd ~
# now also goes to ~/some/long/path/foo
cd foo

You can have multiple keywords as well:

  • cd foo ui could match /foo/bar-ui or /some/path/foo-ui

The only thing you have to remember is that the last keyword has to match the last section of the path you’re trying to get to.

  • cd bar matches /foo/bar, but not /bar/foo
  • cd foo/bar matches /foo/bar, but not /foo/bar/baz
    • it also won’t match /foo/baz/bar, but cd foo bar would!

Imagine never typing cd ../../something again!

SetupSection titled: Setup

The setup is quite straightforward!

Install zoxide with your package manager of choice:

Terminal window
brew install zoxide # with HomeBrew
cargo install zoxide --locked # or with cargo

And then add this to the bottom of your .zshrc file:

# Enable zoxide
# See:
eval "$(zoxide init zsh)"

Now the z command will be available in your terminal, but let’s not waste all that muscle memory you have for typing the letters “c” “d”.

Still in your .zshrc file, above any other aliases you have defined (in case they also use cd), add:

alias cd="z"

Now you’re off to the races! The only thing left to do is take a couple minutes and manually cd around to all your most commonly used paths to teach them to zoxide.

How it worksSection titled: How it works

Zoxide works so well that I got curious to how it functioned behind the scenes. Their solution is both simple and elegant: frequency + recency = frecency

Every time you visit a directory it adds 1 to that directory’s frequency score. Then it adds a multiplier to that score based on the last time you went there:

Last access timeFrecency
Within the last hourscore * 4
Within the last dayscore * 2
Within the last weekscore / 2
Otherwisescore / 4

The match with the highest score wins!

Bonus: Disambiguation & in-terminal UISection titled: Bonus: Disambiguation & in-terminal UI

When you have multiple paths that are similar to each other, if you type your query like normal, then press the space key, and then TAB, a UI will appear that will show you all the matches for that query and let you optionally type to filter the matches further or use the arrow keys to select the one you want.

zoxide in-terminal ui suggestions

Or you can skip the query entirely, and run the zi command in the terminal and you’ll get the same UI that lets you filter through all your stored paths.