.TH "Z" "1" "January 2013" "z" "User Commands"

.SH

NAME

z \- jump around

.SH

SYNOPSIS

z [\-chlrtx] [regex1 regex2 ... regexn]

.SH

AVAILABILITY

bash, zsh

.SH

DESCRIPTION

Tracks your most used directories, based on 'frecency'.

.P

After a short learning phase, \fBz\fR will take you to the most 'frecent'

directory that matches ALL of the regexes given on the command line, in order.

For example, \fBz foo bar\fR would match \fB/foo/bar\fR but not \fB/bar/foo\fR.

.P

If nothing in the jump-list matches, and a single argument was given that names

an existing directory, \fBz\fR acts as a \fBcd\fR alias and goes there. See

\fBcd Fallback\fR below.

.SH

OPTIONS

.TP

\fB\-c\fR

restrict matches to subdirectories of the current directory

.TP

\fB\-e\fR

echo the best match, don't cd

.TP

\fB\-h\fR

show a brief help message

.TP

\fB\-l\fR

list only

.TP

\fB\-r\fR

match by rank only

.TP

\fB\-t\fR

match by recent access only

.TP

\fB\-x\fR

remove the current directory from the datafile

.SH EXAMPLES

.TP 14

\fBz foo\fR

cd to most frecent dir matching foo

.TP 14

\fBz foo bar\fR

cd to most frecent dir matching foo, then bar

.TP 14

\fBz -r foo\fR

cd to highest ranked dir matching foo

.TP 14

\fBz -t foo\fR

cd to most recently accessed dir matching foo

.TP 14

\fBz -l foo\fR

list all dirs matching foo (by frecency)

.TP 14

\fBz foo\fR

cd to ./foo, if nothing in the jump-list matches foo

.TP 14

\fBz ...\fR

cd two directories up

.SH

NOTES

.SS

Installation:

.P

Put something like this in your \fB$HOME/.bashrc\fR or \fB$HOME/.zshrc\fR:

.RS

.P

\fB. /path/to/z.sh\fR

.RE

.P

\fBcd\fR around for a while to build up the db.

.P

PROFIT!!

.P

Optionally:

.RS

Set \fB$_Z_CMD\fR to change the command name (default \fBz\fR).

.RE

.RS

Set \fB$_Z_DATA\fR to change the datafile (default \fB$HOME/.z\fR).

.RE

.RS

Set \fB$_Z_MAX_SCORE\fR lower to age entries out faster (default \fB9000\fR).

.RE

.RS

Set \fB$_Z_NO_RESOLVE_SYMLINKS\fR to prevent symlink resolution.

.RE

.RS

Set \fB$_Z_NO_CD_FALLBACK\fR to not cd to unmatched but existing directories.

.RE

.RS

Set \fB$_Z_NO_FZF\fR to complete without \fBfzf\fR even when it is installed.

.RE

.RS

Set \fB$_Z_FZF_PRUNE_DIRS\fR to an array of directory names \fBfzf\fR shouldn't

offer.

.RE

.RS

Set \fB$_Z_NO_PROMPT_COMMAND\fR to handle \fBPROMPT_COMMAND/precmd\fR yourself.

.RE

.RS

Set \fB$_Z_EXCLUDE_DIRS\fR to an array of directory trees to exclude.

.RE

.RS

Set \fB$_Z_OWNER\fR to allow usage when in 'sudo -s' mode.

.RE

.RS

(These settings should go in .bashrc/.zshrc before the line added above.)

.RE

.RS

Install the provided man page \fBz.1\fR somewhere in your \fB$MANPATH\fR, with

\fBmake install-man\fR, or by hand into a directory such as

\fB/usr/local/share/man/man1\fR. Then \fBman z\fR works.

.RE

.SS

Aging:

The rank of directories maintained by \fBz\fR undergoes aging based on a simple

formula. The rank of each entry is incremented every time it is accessed. When

the sum of ranks is over 9000, all ranks are multiplied by 0.99. Entries with a

rank lower than 1 are forgotten.

.SS

Frecency:

Frecency is a portmanteau of 'recent' and 'frequency'. It is a weighted rank

that depends on how often and how recently something occurred. As far as I

know, Mozilla came up with the term.

.P

To \fBz\fR, a directory that has low ranking but has been accessed recently

will quickly have higher rank than a directory accessed frequently a long time

ago.

.P

Frecency is determined at runtime.

.SS

Common:

When multiple directories match all queries, and they all have a common prefix,

\fBz\fR will cd to the shortest matching directory, without regard to priority.

This has been in effect, if undocumented, for quite some time, but should

probably be configurable or reconsidered.

.SS

Going Up:

An argument of nothing but dots walks up the tree, one directory per dot past

the first: \fBz ..\fR is the parent, \fBz ...\fR its parent, \fBz ....\fR the

one above that. Asking for more levels than there are stops at \fB/\fR. A

single \fB.\fR is left alone, since it is a perfectly good regex.

.P

This is checked before the datafile, because as a regex \fB..\fR matches almost

every path in it, and so used to jump somewhere arbitrary.

.SS

cd Fallback:

When no directory in the datafile matches the query, \fBz\fR falls back to

behaving like \fBcd\fR: if exactly one argument was given, and it is a path to

an existing directory, \fBz\fR cds to it. This makes \fBz\fR usable on

directories it has never seen, such as freshly created ones.

.P

The datafile always takes priority, so a query that matches a known directory

jumps there even if a directory of the same name exists in \fB$PWD\fR. The

fallback is also skipped for \fB\-l\fR and \fB\-e\fR, and can be disabled

entirely by setting \fB$_Z_NO_CD_FALLBACK\fR.

.SS

Tab Completion:

\fBz\fR supports tab completion. After any number of arguments, press TAB to

complete on directories that match each argument. Due to limitations of the

completion implementations, only the last argument will be completed in the

shell.

.P

If \fBfzf\fR(1) is installed, TAB opens it instead of completing in place.

The candidates are the whole jump-list, most 'frecent' first, then the

subdirectories of \fB$PWD\fR, then its parent and your siblings, so the picker

can go up and across as well as down. \fB$PWD\fR itself is left out. Whatever

you had typed becomes the starting query, and a single match is taken without

drawing the picker at all, so TAB on an unambiguous query stays instant.

.P

TAB inside the picker looks inside the highlighted directory: the list is

replaced by what surrounds that directory, as though you had jumped there and

pressed TAB again, and the directory itself is offered first so that return goes

where you just looked. The query is cleared, since it has already served its

purpose. Press TAB repeatedly to walk down a tree a level at a time.

.P

In zsh the directory you choose is jumped to immediately: TAB is a widget

there, so the jump runs as \fB${_Z_CMD:-z} <dir>\fR, which also puts it in your

history, and cancelling the picker discards the line the way \fB^C\fR does.

bash's readline cannot run a command from a completion, so there the choice is

inserted on the command line for you to accept with return.

.P

Only one level either side of the directory being looked at is offered, so the

list stays short and TAB stays instant; depth comes from the jump-list, and from

pressing TAB.

\fB.git\fR, \fB.hg\fR, \fB.svn\fR and \fBnode_modules\fR are left out, as are

any names in \fB$_Z_FZF_PRUNE_DIRS\fR. Appearance and keybindings come from

\fBfzf\fR's own \fB$FZF_DEFAULT_OPTS\fR. Set \fB$_Z_NO_FZF\fR to complete in

place instead.

.P

Internally, \fBz\fR decides you've requested a completion if the last argument

passed is an absolute path to an existing directory. This may cause unexpected

behavior if the last argument to \fBz\fR begins with \fB/\fR.

.SH

ENVIRONMENT

A function \fB_z()\fR is defined.

.P

The contents of the variable \fB$_Z_CMD\fR is aliased to \fB_z 2>&1\fR. If not

set, \fB$_Z_CMD\fR defaults to \fBz\fR.

.P

The environment variable \fB$_Z_DATA\fR can be used to control the datafile

location. If it is not defined, the location defaults to \fB$HOME/.z\fR.

.P

The environment variable \fB$_Z_NO_RESOLVE_SYMLINKS\fR can be set to prevent

resolving of symlinks. If it is not set, symbolic links will be resolved when

added to the datafile.

.P

The environment variable \fB$_Z_NO_CD_FALLBACK\fR can be set to prevent \fBz\fR

from falling back to \fBcd\fR when the query matches nothing in the datafile.

.P

The environment variable \fB$_Z_NO_FZF\fR can be set to complete in place even

when \fBfzf\fR is installed. \fB$_Z_FZF_PRUNE_DIRS\fR can be set to an array of

directory names to leave out when listing subdirectories; it adds to the

always-omitted \fB.git\fR, \fB.hg\fR, \fB.svn\fR and \fBnode_modules\fR.

.P

In bash, \fBz\fR appends a command to the \fBPROMPT_COMMAND\fR environment

variable to maintain its database. In zsh, \fBz\fR appends a function

\fB_z_precmd\fR to the \fBprecmd_functions\fR array.

.P

In zsh with \fBfzf\fR installed, \fBz\fR binds TAB to a \fBzle\fR widget,

\fB_z_zsh_tab_widget\fR, so that picking a directory can run the jump instead of

only typing it out. The widget hands TAB straight to whatever it was bound to

before for every line that isn't a \fBz\fR command, so other completions are

untouched; with \fB$_Z_NO_FZF\fR set at the time \fBz.sh\fR is sourced, TAB is

left alone entirely.

.P

In zsh, \fBz\fR registers its completion with \fBcompctl\fR and, when the newer

completion system is loaded, with \fBcompdef\fR as well. The latter is required:

\fBcompinit\fR ignores \fBcompctl\fR, and completes the alias by expanding it to

\fB_z\fR, which zsh's own \fB_compadd\fR claims for every \fB_*\fR command. If

\fBcompinit\fR has not run by the time \fBz.sh\fR is sourced, the \fBcompdef\fR

call is retried once from \fBprecmd_functions\fR; with

\fB$_Z_NO_PROMPT_COMMAND\fR set there is no retry, so source \fBz.sh\fR after

\fBcompinit\fR.

.P

The environment variable \fB$_Z_NO_PROMPT_COMMAND\fR can be set if you want to

handle \fBPROMPT_COMMAND\fR or \fBprecmd\fR yourself.

.P

The environment variable \fB$_Z_EXCLUDE_DIRS\fR can be set to an array of

directory trees to exclude from tracking. \fB$HOME\fR is always excluded.

Directories must be full paths without trailing slashes.

.P

The environment variable \fB$_Z_OWNER\fR can be set to your username, to

allow usage of \fBz\fR when your sudo environment keeps \fB$HOME\fR set.

.SH

FILES

Data is stored in \fB$HOME/.z\fR. This can be overridden by setting the

\fB$_Z_DATA\fR environment variable. When initialized, \fBz\fR will raise an

error if this path is a directory, and not function correctly.

.P

A man page (\fBz.1\fR) is provided.

.SH

SEE ALSO

regex(7), fzf(1), pushd, popd, autojump, cdargs

.P

Please file bugs at https://github.com/rupa/z/