.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} \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/