You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
170 lines
4.9 KiB
170 lines
4.9 KiB
.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/
|
|
|