171 lines
4.9 KiB
Groff
171 lines
4.9 KiB
Groff
.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.
|
|
.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)
|
|
.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_NO_RESOLVE_SYMLINKS\fR to prevent symlink resolution.
|
|
.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 \f$MANPATH, like
|
|
\fB/usr/local/man/man1\fR.
|
|
.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
|
|
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
|
|
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
|
|
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
|
|
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), pushd, popd, autojump, cdargs
|
|
.P
|
|
Please file bugs at https://github.com/rupa/z/
|