Z(1) User Commands Manual Z(1)
NAME
z -- jump around
SYNOPSIS
z [-hclrtx] [string ...]
AVAILABILITY
bash, zsh
DESCRIPTION
Tracks your most used directories, based on `frecency'. After a short
learning phase, z will take you to the most `frecent' directory that
matches all of the patterns given on the command line.
Each pattern is a substring that the directory to look for must contain,
not a regular expression like in the original version nor a glob pattern
that you can use in shell completion described below.
For convenience, a trailing slash in a pattern is treated specially so
that the pattern also matches directories ending with the pattern string
minus the trailing slash. That is, for instance, a pattern `log/'
matches /var/log as well as /service/nginx/log/main, but not
/home/user/logs.
In addition to this, a double slash at the beginning or at the end of a
pattern has special meanings. A double slash at the beginning denotes
the root directory, and a double slash at the end denotes the end of a
path. That is, a pattern `//var' matches /var/log but does not match
/home/user/var/log, and a pattern `src//' matches
/home/user/src/screen/src but does not match /home/user/src/screen.
The $HOME part in a directory name is excluded before matching so that a
word or substring that is in your account name does not hit every single
directory under your home directory.
OPTIONS
-h Show a brief help message.
-c Restrict matches to subdirectories of the current directory.
-l List only.
-r Sort by rank instead of `frecency'.
-t Sort by recency instead of `frecency'.
-x Remove the current directory from the datafile.
Nonexistent directories are omitted from output and ignored in moving and
completion but kept in database for future use.
In listing, only top 20 directories are shown if stdout is a terminal.
To show all, run z with a pipe, like `z | cat' or `z | less'.
EXAMPLES
z foo cd to most frecent directory matching foo
z foo bar cd to most frecent directory matching foo and bar
z -r foo cd to highest ranked directory matching foo
z -t foo cd to most recently accessed directory matching foo
z -l foo list all directories matching foo (by frecency)
NOTES
Installation:
1. Source z.sh from your $HOME/.bashrc or $HOME/.zshrc like this:
. /path/to/z.sh
Note that if you are using bash:
- The line should go something like this:
[[ -z $PS1 ]] || . /path/to/z.sh
because bash(1) in some cases reads $HOME/.bashrc when the
shell is not interactive and z.sh will emit an error message
in that case.
- The line should better be put after defining a completion
method for cd if any, because z.sh tries to enhance an
existing completion definition.
2. cd around for a while to build up the db.
3. PROFIT!!
Optionally:
Set _Z_CMD to change the command name (default `z').
Set _Z_DATA to change the data file name (default `$HOME/.z').
Set _Z_NO_COMPLETE_CD to disable advanced completion for cd.
Set _Z_NO_RESOLVE_SYMLINKS to prevent symlink resolution.
Set _Z_NO_PROMPT_COMMAND to handle PROMPT_COMMAND (bash) / precmd
(zsh) yourself.
Set _Z_EXCLUDE_DIRS to an array of directories to exclude.
These settings should go in .bashrc / .zshrc before the line added above.
Install the provided man page z.1 to somewhere in the man path like
/usr/local/man/man1.
Aging:
The rank of directories maintained by z 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 greater than 6000, all ranks are
multiplied by 0.99. Entries with a rank lower than 1 are forgotten.
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.
To z, 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.
Frecency is determined at runtime.
Common:
When multiple directories match all queries, and they all have a common
prefix, z 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.
Shell Completion:
z supports interactive shell completion. After typing a string fragment,
press TAB to complete on directories that matches the pattern. In
addition to the double slash notation described above, and glob matching
works here.
z also enhances the completion for the cd command so you don't even need
to learn about z at all. If you don't like this feature, it can be
disabled. See the next section.
ENVIRONMENT
A function _z_cmd() is defined.
The contents of the variable _Z_CMD is aliased to `_z_cmd'. If not set,
_Z_CMD defaults to z. The environment variable _Z_DATA can be used to
control the data file location. If it is not defined, the location
defaults to `$HOME/.z'.
The environment variable _Z_NO_RESOLVE_SYMLINKS can be set to prevent
resolving of symlinks. If it is not set, symbolic links will be resolved
when added to the data file.
In bash, z prepends a command to the PROMPT_COMMAND environment variable
to maintain its database. In zsh, z appends a function _z_precmd to the
precmd_functions array.
The environment variable _Z_NO_COMPLETE_CD can be set to disable advanced
completion for cd.
The environment variable _Z_NO_PROMPT_COMMAND can be set if you want to
handle PROMPT_COMMAND or precmd yourself.
The environment variable _Z_EXCLUDE_DIRS can be set to an array of
directories to exclude from tracking. HOME is always excluded. Each
element must be an absolute path, and if it ends with a slash, all its
subdirectories are also excluded.
FILES
Data is stored in $HOME/.z. This can be overridden by setting the _Z_DATA
environment variable. When initialized, z will raise an error if this
path is a directory, and not function correctly.
A man page (z.1) is provided.
SEE ALSO
autojump(1), bash(1), cdargs(1), j(1), zshall(1)
AUTHORS
rupa deadwyler <rupa@lrrr.us>
Akinori MUSHA <knu@iDaemons.org>
HISTORY
z was originally deveoloped by rupa deadwyler as a successor to j(1), a
python free alternative to Joel Schaerer's autojump(1). The original
version is maintained at <https://github.com/rupa/z>.
This fork was started by Akinori MUSHA in early 2013 to improve zsh/bash
completion usability and search results.
The pattern matching conventions described above are exclusive features
of this fork, while the data file format and the core algorithm are kept
compatible with those of the original version.
BUGS
Please file bugs at <https://github.com/knu/z>.
Unix June 24, 2013 Unix