135 lines
4.0 KiB
Groff
135 lines
4.0 KiB
Groff
.TH "ZOXIDE" "1" "2021-04-12" "" "zoxide"
|
|
.SH NAME
|
|
\fBzoxide\fR - a smarter cd command
|
|
.SH SYNOPSIS
|
|
.B zoxide SUBCOMMAND [OPTIONS]
|
|
.SH DESCRIPTION
|
|
zoxide is a smarter cd command for your terminal. It keeps track of the
|
|
directories you use most frequently, and uses a ranking algorithm to navigate
|
|
to the best match.
|
|
.SH USAGE
|
|
.nf
|
|
z foo # cd into highest ranked directory matching foo
|
|
z foo bar # cd into highest ranked directory matching foo and bar
|
|
z foo / # cd into a subdirectory starting with foo
|
|
.sp
|
|
z ~/foo # z also works like a regular cd command
|
|
z foo/ # cd into relative path
|
|
z .. # cd one level up
|
|
z - # cd into previous directory
|
|
.sp
|
|
zi foo # cd with interactive selection (using fzf)
|
|
.sp
|
|
z foo<SPACE><TAB> # show interactive completions (bash 4.4+/fish/zsh only)
|
|
.fi
|
|
.SH SUBCOMMANDS
|
|
.TP
|
|
\fBzoxide-add\fR(1)
|
|
Add a new directory to the database, or increment its rank.
|
|
.TP
|
|
\fBzoxide-import\fR(1)
|
|
Import entries from another application.
|
|
.TP
|
|
\fBzoxide-init\fR(1)
|
|
Generate shell configuration.
|
|
.TP
|
|
\fBzoxide-query\fR(1)
|
|
Search for a directory in the database.
|
|
.TP
|
|
\fBzoxide-remove\fR(1)
|
|
Remove a directory from the database.
|
|
.SH OPTIONS
|
|
.TP
|
|
.B -h, --help
|
|
Print help information.
|
|
.TP
|
|
.B -V, --version
|
|
Print version information.
|
|
.SH ENVIRONMENT VARIABLES
|
|
Environment variables can be used for configuration. They must be set before
|
|
\fBzoxide-init\fR(1) is called.
|
|
.TP
|
|
.B _ZO_DATA_DIR
|
|
Specifies the directory in which the database is stored. The default value
|
|
varies across OSes:
|
|
.TS
|
|
tab(|);
|
|
l l.
|
|
\fBOS|Path\fR
|
|
\fBLinux/BSD\fR|T{
|
|
\fB$XDG_DATA_HOME\fR or \fB$HOME/.local/share\fR, eg.
|
|
\fB/home/alice/.local/share\fR
|
|
T}
|
|
\fBmacOS\fR|T{
|
|
\fB$HOME/Library/Application Support\fR, eg.
|
|
\fB/Users/Alice/Library/Application Support\fR
|
|
T}
|
|
\fBWindows\fR|T{
|
|
\fB%LOCALAPPDATA%\fR, eg. \fBC:\\Users\\Alice\\AppData\\Local\fR
|
|
T}
|
|
.TE
|
|
.TP
|
|
.B _ZO_ECHO
|
|
When set to 1, \fBz\fR will print the matched directory before navigating to it.
|
|
.TP
|
|
.B _ZO_EXCLUDE_DIRS
|
|
Prevents the specified directories from being added to the database. This is
|
|
provided as a list of globs, separated by OS-specific characters:
|
|
.TS
|
|
tab(|);
|
|
l l.
|
|
\fBOS|Separator\fR
|
|
\fBLinux/macOS/BSD\fR|T{
|
|
\fB:\fR, eg. \fB$HOME:$HOME/private/*\fR
|
|
T}
|
|
\fBWindows\fR|\fB;\fR, eg. \fB$HOME;$HOME/private/*\fR
|
|
.TE
|
|
.sp
|
|
By default, this is set to \fB$HOME\fR. After setting this up, you might need
|
|
to use \fBzoxide-remove\fR(1) to remove any existing entries from the database.
|
|
.TP
|
|
.B _ZO_FZF_OPTS
|
|
Custom options to pass to \fBfzf\fR(1) during interactive selection. See the
|
|
manpage for the full list of options.
|
|
.TP
|
|
.B _ZO_MAXAGE
|
|
Configures the aging algorithm, which limits the maximum number of entries in
|
|
the database. By default, this is set to 10000.
|
|
.TP
|
|
.B _ZO_RESOLVE_SYMLINKS
|
|
When set to 1, \fBz\fR will resolve symlinks before adding directories to
|
|
the database.
|
|
.SH ALGORITHM
|
|
.TP
|
|
.B AGING
|
|
zoxide uses a parameter called \fB_ZO_MAXAGE\fR to limit the number of entries
|
|
in the database based on usage patterns. If the total \fBFRECENCY\fR of the
|
|
directories in the database exceeds this value, we divide each directory's
|
|
score by a factor \fBk\fR - such that the new total becomes ~90% of
|
|
\fB_ZO_MAXAGE\fR. Thereafter, if the new score of any directory falls below
|
|
1, it is removed from the database.
|
|
.sp
|
|
Theoretically, the maximum number of directories in the database is
|
|
\fB4 * _ZO_MAXAGE\fR, although it is lower in practice.
|
|
.TP
|
|
.B FRECENCY
|
|
Each directory in zoxide is given a score, starting with 1 the first time
|
|
it is accessed. Every subsequent access increases the score by 1. When a
|
|
query is made, we calculate frecency based on the last time the directory was
|
|
accessed:
|
|
.TS
|
|
tab(|);
|
|
l l.
|
|
\fBLast access time\fR|\fBFrecency\fR
|
|
Within the last hour|score * 4
|
|
Within the last day|score * 2
|
|
Within the last week|score / 2
|
|
Otherwise|score / 4
|
|
.TE
|
|
.SH REPORTING BUGS
|
|
For any issues, feature requests, or questions, please visit:
|
|
.sp
|
|
\fBhttps://github.com/ajeetdsouza/zoxide/issues\fR
|
|
.SH AUTHOR
|
|
Ajeet D'Souza \fB<98ajeet@gmail.com>\fR
|