smart change of directory in a Unix shell, IPython and Vim
Shell Vim script Python
Switch branches/tags
Latest commit 2603f1e May 8, 2017 @pavoljuhas Trim index in a background process.
Avoid long delay due to checking existence and possibly name
capitalization of many directories.
Failed to load latest commit information.

smart-change-directory (scd)

Z shell function for visiting any directory in a unix shell, Vim or IPython.

scd is a Z shell (Zsh) script for changing to any directory with a few keystrokes. scd keeps history of the visited directories, which serves as an index of the known paths. The directory index is updated after every cd command in the shell and can be also filled manually by running scd -a. To switch to some directory, scd needs few fragments of the desired path to match with the index. A selection menu is displayed in case of several matches, with a preference given to recently visited paths. scd can create permanent directory aliases, which directly map to the target path.


scd [options] [pattern1 pattern2 ...]


-a, --add
add current or specified directories to the directory index.


remove current or specified directories from the index.

-r, --recursive

apply options --add or --unindex recursively.


create alias for the current or specified directory and save it to ~/.scdalias.zsh.


remove ALIAS definition for the current or specified directory from ~/.scdalias.zsh.

-A, --all

display all directories even those excluded by patterns in ~/.scdignore. Disregard the unique matching for a directory alias and filtering of less likely paths.


show matching directories and exit.

-v, --verbose

display directory rank in the selection menu.

-h, --help

display this options summary and exit.


Unix shell

  1. Make sure that Z shell is installed. On Linux it is usually the zsh package.

  2. Copy or symlink the bin/scd script to some directory in the PATH.

  3. Find out what shell is active for your account by running ps -p $$.

  4. Edit the startup file for your shell and have it source the corresponding scd setup file from shellrcfiles as follows:

    • zsh

      # ~/.zshrc
      source ~/Software/smart-change-directory/shellrcfiles/zshrc_scd

      Note that scd aliases are named directories in Zsh and can be thus expanded as ~NAME in the shell. If you use the oh-my-zsh framework you may just activate the scd plugin instead. If you have zsh 4.2 or older source zshrc_scd_42.

    • bash

      # ~/.bashrc
      source ~/Software/smart-change-directory/shellrcfiles/bashrc_scd
    • tcsh

      # ~/.cshrc
      source ~/Software/smart-change-directory/shellrcfiles/tcshrc_scd
    • dash

      # add to ~/.profile or to the ${ENV} file
      . ~/Software/smart-change-directory/shellrcfiles/dashrc_scd


# Index recursively some paths for the very first run
scd -ar ~/Documents/

# Change to a directory path matching "doc"
scd doc

# Change to a path matching all of "a", "b" and "c"
scd a b c

# Change to a directory path that ends with "ts"
scd "ts$"

# Show selection menu and ranking of 20 most likely directories
scd -v

# Alias current directory as "xray"
scd --alias=xray

# Jump to a previously defined aliased directory
scd xray

Installation as Vim plugin

  1. Copy or symlink vim/plugin/scd.vim file to the ~/.vim/plugin/ directory or source it from .vimrc.

  2. If scd is not in the PATH, set the g:scd_command variable in .vimrc to specify its location.

    let g:scd_command = '/path/to/scd'
  3. When Vim is set to use zsh for system commands :set shell=/bin/zsh, scd aliases can be expanded in Vim command mode, as in :e ~foo/file.txt. Allow this by adding the following line to ~/.zshenv

    if [[ -s ~/.scdalias.zsh ]]; then source ~/.scdalias.zsh; fi


" add ~/.vim/ and its subdirectories to the scd directory index
:Scd -ar ~/.vim

" jump to the ~/.vim/ftplugin/ directory
:Scd vi ftpl

" change to a recent directory ending with "im"
:Scd im$

" show selection menu with directories ranked by likelihood
:Scd -v

" same as Scd, but use the :lcd Vim command

" complete scd-defined directory aliases
:Scd <Tab>

" display a brief usage information for :Scd
:Scd --help

Installation as IPython extension

  1. Copy or symlink ipython/ to some directory in Python module path.

  2. In IPython terminal session do %load_ext ipy_scd to define the %scd magic command. This also modifies the %cd, %pushd, %popd magics to add directories to the scd index. To load ipy_scd for every IPython session, modify .../profile_default/ so that it contains

    c.TerminalIPythonApp.extensions = ['ipy_scd']
  3. If scd is not in the PATH, its location can be defined with

    import ipy_scd
    ipy_scd.scd_executable = '/path/to/scd'


# recursively index ~/.local/ and its subdirectories
%scd -ar ~/.local

# jump to the site-packages directory (if exists in ~/.local)
%scd site pack


time-stamped index of visited directories.


scd-generated definitions of directory aliases.


glob patterns for paths to be ignored in the scd search, for example, /mnt/backup/*. The patterns are specified one per line and are matched assuming the extendedglob zsh option. Lines starting with "#" are skipped as comments. The .scdignore patterns are not applied in the --all mode.


path to the scd index file (by default ~/.scdhistory).


maximum number of entries in the index (5000). Index is trimmed when it exceeds SCD_HISTSIZE by more than 20%.


maximum number of items for directory selection menu (20).


mean lifetime in seconds for exponential decay of directory likelihood (86400).


threshold for cumulative directory likelihood. Directories with a lower likelihood compared to the best match are excluded (0.005).


command script file where scd writes the final cd command. This variable must be defined when scd runs in its own process rather than as a shell function. It is up to the scd caller to use the output in SCD_SCRIPT.