cdhist 5.2

CDHIST - Linux Directory History

cdhist is a utility which provides a Linux shell cd history directory stack. A shell cd wrapper function calls cdhist to intercept your typed cd command and maintain an ordered stack of all directories you have previously visited which can be listed and quickly navigated to.

cdhist can also be used with a fuzzy finder (such as fzf) to fuzzy search and select on previously visited directories.

The latest version and documentation is available at http://github.com/bulletmark/cdhist.

Example Usage

Use the cd command to change directory as normal:

$ cd /tmp
$ cd /etc
$ cd /usr/share/doc
$ cd /boot/loader
$ cd ~/etc
$ cd

At any point you can use the cd -- command to list all your previously visited directories and be prompted for one to select and cd to:

$ cd --
  6 ...
  5 /tmp
  4 /etc
  3 /usr/share/doc
  2 /boot/loader
  1 ~/etc
  0 ~
Select index [or <enter> to quit]: 3
$ pwd
/usr/share/doc

That's it! The above is all you really need to know. Instead of having to type the directory name you merely enter it's index. The directories are displayed most recently visited last, without duplicates. Index 0 is the current directory, index 1 is the previous, index 2 is the second previous, up to a user configurable number (default 200).

If you prefer a more modern approach you can use a fuzzy finder such as fzf, sk, tv, or fzy to show and select from the list, instead of a simple index prompt. See the section on Fuzzy Finder Integration below.

Other available commands and options are:

List the current stack and its indices (without prompting):

$ cd -l

Change immediately to directory corresponding to stack index 4:

$ cd -4

Note that cd -1 is equivalent to the native cd - for the previous directory, cd -2 is the directory before that, etc.

Search back through stack for directory containing "string" in it's name and cd there:

$ cd -/string

Note, you can also type the text string at the cd -- prompt to search, although for frequent searching it is probably better to use an integrated fuzzy finder.

Show help/usage:

$ cd -h

Installation

Arch users can install cdhist from the AUR and skip to the next section.

Python 3.8 or later is required. Note cdhist is on PyPI so the easiest way to install it is to use uv tool (or pipx or pipxu).

$ uv tool install cdhist

To upgrade:

$ uv tool upgrade cdhist

To uninstall:

$ uv tool uninstall cdhist

Setup

A user who wants to use the cdhist facility should add the following line to their ~/.bashrc or ~/.zshrc file. Ensure it is added after where your PATH is set up so that the command cdhist can be found. This creates the cd wrapper command in your interactive shell session as a tiny function.

source <(cdhist -i)

Then log out and back in again to activate the new cd function. Note assuming a normal .bashrc environment, this will alias your cd command in your interactive terminal session only. The remapped cd will not be invoked by any programs or scripts you run, or for other users etc.

Alternative Command Name

Some people may prefer not to alias their real cd command to this utility and just use an alternative unique command name. To do this, simply add your desired command name as the first argument to the cdhist -i option in your shell initialization code. E.g, to use the command name xd rather than cd, use the following in your ~/.bashrc or ~/.zshrc file:

source <(cdhist -i xd)

Then log out/in, and then use xd /tmp to change dir, xd -- to see and select directories, etc.

Default Options

You can set default cdhist options by appending options in the shell initialization code, e.g:

source <(cdhist -i "cd -am 100")

The above sets -a/--purge-always and -m/--size 100 options as defaults for your cd command.

The following options are sensible candidates to set as default options: -m/--size, -a/--purge-always, -u/--no-user, -F/--fuzzy.

Note if you set -u/--no-user options as default then option -U/--user exist to allow you to temporarily override those defaults via the command line.

Fuzzy Finder Integration

Any of the popular command line fuzzy search finders such as fzf, sk, tv, or fzy can be used with cdhist.

E.g. to use fzf:

source <(cdhist -i "cd -F fzf")

Now when you type cd -- you will be prompted with a list of directories via your fuzzy finder so you can search for a directory to select by fuzzy text matching.

Or, to use fzf with preview of directory contents using eza:

source <(cdhist -i "cd -uF \"fzf --preview 'eza --color=always -lF {} 2>/dev/null'\"")

Note that fzf will be used in the following description as it is by far the most popular fuzzy finder and the one used by the author. When you set up fzf shell integration then you can use the following terminal key bindings for fzf:

• CTRL+t to select files,
• CTRL+r to select commands,
• ATL+c to select directories.

However, I never use the last ATL+c function because it lists directories only under the current directory whereas I am much more interested in listing all directories I have previously visited, i.e. those maintained by cdhist. So I disable that function in fzf by setting the FZF_ALT_C_COMMAND to an empty string before I source fzf in my .bashrc when setting fzf up.

Then I set the following shell key binding in my ~/.inputrc file (need to restart your login shell/terminal to activate):

"\ec": "cd --\n"

Now pressing ALT+c invokes cdhist to bring up the fzf list of my previously visited directories. Alternately, use ALT+d for cdhist and keep ALT+c for the default fzf search behavior.

You also have the choice of keeping the standard cd -- command to work with simple index selection, and map a different cdhist command name to use with ALT+c only for the fuzzy finder. To do this, add the following 2 lines to your ~/.bashrc or ~/.zshrc file:

source <(cdhist -i)
source <(cdhist -i "cdfuzzy -F fzf")

And then in your ~/.inputrc:

"\ec": "cdfuzzy --\n"

Note all the above assumes you have the fuzzy finder somewhere in your PATH. If you don't then just specify the full path, e.g:

source <(cdhist -i "cd -F /path-to/fzf")

Yazi Integration

cdhist.yazi is a yazi plugin that provides cdhist functionality within the yazi terminal file manager.

GIT Worktree Integration

The cdhist utility previously provided an option to switch between git worktree directories. However, this functionality has been removed in August 2026 (at version 4.6) since the author has developed a much better dedicated utility worktree-aid which users are encouraged to use instead. worktree-aid (as shell function/alias wt) can be used in parallel and in concert with cdhist to provide a more comprehensive solution for switching between, adding, and removing git worktrees.

Usage

Type cd -h to view the usage summary:

usage: cd [-i] [-l] [-m SIZE] [-n NUM_LINES] [-p] [-a] [-u] [-F FUZZY]
              [-L] [-P] [-V] [-h]
              [directory]

A Linux shell directory stack "cd history" function.

positional arguments:
  directory             directory to cd to, or "--" to list history and
                        prompt, or "-n" for n'th entry in list or "-/<string>"
                        to match for "string" in dir

options:
  -i, --init            output shell initialization code. Optionally specify
                        alternative command name as argument, default="cd"
  -l, --list            just list directory history
  -m, --size SIZE       maximum size of directory history (default=200)
  -n, --num-lines NUM_LINES
                        limit output to specified number of lines
  -p, --purge           just purge non-existent directories from history
  -a, --purge-always    always purge non-existent directories every write
  -u, --no-user         toggle substitution of "~" for user home directory,
                        default is to substitute. Can be specified on command
                        line again to toggle your default setting.
  -F, --fuzzy FUZZY     use specified fuzzy finder program to select directory
                        from list
  -L, --follow-links    follow symbolic links (default=true)
  -P, --follow-physical
                        follow links to physical directory
  -V, --version         show program version and exit
  -h, --help            show help message and exit

Limitations

Regular cd, e.g. as provided by the bash builtin, offers some esoteric command line options such as -e and -@, and shell options such as autocd, cdspell, cdable_vars. These rarely used options are not supported by cdhist.

License

GPL-3.0-or-later.