ohmyzsh/plugins/scd

scd - smart change of directory

Define scd shell function 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 appear as named directories in zsh session.

INSTALLATION NOTES

Besides oh-my-zsh, scd can be used with bash, dash or tcsh
shells and is also available as Vim plugin
scd.vim and
IPython extension. For installation details, see
https://github.com/pavoljuhas/smart-change-directory.

SYNOPSIS

scd [options] [pattern1 pattern2 ...]

PATTERNS

Patterns may use all zsh glob operators
available with extendedglob option. Specified patterns must match
the absolute path and at least one of them must match in the tail.
Several special patterns are also recognized as follows:

^PAT

PAT must match at the beginning of the path, for example, "^/home"

PAT$

require PAT to match the end of the path, "man$"

./

match only subdirectories of the current directory

:PAT

require PAT to match over the tail component, ":doc", ":re/doc"

OPTIONS

-a, --add

add current or specified directories to the directory index.

--unindex

remove current or specified directories from the index.

-r, --recursive

apply options --add or --unindex recursively.

--alias=ALIAS

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

--unalias

remove ALIAS definition for the current or specified directory from
~/.scdalias.zsh. Use "OLD" to purge aliases to non-existent
directories.

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

-p, --push

use "pushd" to change to the target directory.

--list

show matching directories and exit.

-v, --verbose

display directory rank in the selection menu.

-h, --help

display this options summary and exit.

Examples

# 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

FILES

~/.scdhistory

time-stamped index of visited directories.

~/.scdalias.zsh

scd-generated definitions of directory aliases.

~/.scdignore

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.

ENVIRONMENT

SCD_HISTFILE

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

SCD_HISTSIZE

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

SCD_MENUSIZE

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

SCD_MEANLIFE

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

SCD_THRESHOLD

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

SCD_SCRIPT

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.