From 1828414f21989ecd588c354a19b8609e03b90f07 Mon Sep 17 00:00:00 2001 From: Ajeet D'Souza <98ajeet@gmail.com> Date: Thu, 15 Apr 2021 19:17:15 +0530 Subject: [PATCH] Add manpage (#183) --- man/zoxide-add.1 | 24 +++++++ man/zoxide-import.1 | 31 +++++++++ man/zoxide-init.1 | 111 ++++++++++++++++++++++++++++++++ man/zoxide-query.1 | 27 ++++++++ man/zoxide-remove.1 | 21 +++++++ man/zoxide.1 | 150 ++++++++++++++++++++++++++++++++++++++++++++ src/cmd/import.rs | 2 +- src/cmd/query.rs | 8 +-- src/cmd/remove.rs | 1 + 9 files changed, 370 insertions(+), 5 deletions(-) create mode 100644 man/zoxide-add.1 create mode 100644 man/zoxide-import.1 create mode 100644 man/zoxide-init.1 create mode 100644 man/zoxide-query.1 create mode 100644 man/zoxide-remove.1 create mode 100644 man/zoxide.1 diff --git a/man/zoxide-add.1 b/man/zoxide-add.1 new file mode 100644 index 0000000..6760a4b --- /dev/null +++ b/man/zoxide-add.1 @@ -0,0 +1,24 @@ +.TH "zoxide-add" "1" "2021-04-12" "zoxide" "zoxide" +.SH NAME +zoxide-add - add a new directory or increment its rank +.SH SYNOPSIS +.B zoxide add \fIPATH\fR +.SH DESCRIPTION +If the directory is not already in the database, this command creates a new +entry for it with a default score of \fI1\fR, otherwise, it increments the +existing score by \fI1\fR. It then sets the last updated field of the entry to the +current time. After this, it runs the \fBAGING\fR algorithm on the database. See +\fBzoxide\fR(1) for more about the algorithm. +.sp +If you'd like to prevent a directory from being added to the database, see the +\fB_ZO_EXCLUDE_DIRS\fR environment variable in \fBzoxide\fR(1). +.SH OPTIONS +.TP +.B -h, --help +Prints help information +.SH REPORTING BUGS +For any issues, feature requests, or questions, please visit: +.sp + \fIhttps://github.com/ajeetdsouza/zoxide/issues\fR +.SH AUTHOR +Ajeet D'Souza <\fI98ajeet@gmail.com\fR> diff --git a/man/zoxide-import.1 b/man/zoxide-import.1 new file mode 100644 index 0000000..cdb77de --- /dev/null +++ b/man/zoxide-import.1 @@ -0,0 +1,31 @@ +.TH "zoxide-import" "1" "2021-04-12" "zoxide" "zoxide" +.SH NAME +zoxide-import - import data from other tools +.SH SYNOPSIS +.B zoxide import \fIPATH --from FORMAT [OPTIONS]\fR +.SH OPTIONS +.TP +.B --from \fIFORMAT\fR +The format of the database being imported: +.TS +tab(|); +l l. + \fIautojump\fR + \fIz\fR|For \fIz\fR, \fIz.lua\fR, or \fIzsh-z\fR. +.TE +.sp +\fBNOTE\fR: zoxide only imports paths from autojump, since its matching +algorithm is too different to import the scores. +.TP +.B -h, --help +Prints help information +.TP +.B --merge +By default, the import fails if the current database is not already empty. This +option merges imported data into the existing database. +.SH REPORTING BUGS +For any issues, feature requests, or questions, please visit: +.sp + \fIhttps://github.com/ajeetdsouza/zoxide/issues\fR +.SH AUTHOR +Ajeet D'Souza <\fI98ajeet@gmail.com\fR> diff --git a/man/zoxide-init.1 b/man/zoxide-init.1 new file mode 100644 index 0000000..0625ba7 --- /dev/null +++ b/man/zoxide-init.1 @@ -0,0 +1,111 @@ +.TH "zoxide-init" "1" "2021-04-12" "zoxide" "zoxide" +.SH NAME +zoxide-init - generate shell configuration for zoxide +.SH SYNOPSIS +.B zoxide init \fISHELL [OPTIONS]\fR +.SH DESCRIPTION +To initialize zoxide on your shell: +.TP +.B bash +Add the following line to your configuration file (usually \fI~/.bashrc\fR): +.sp +.nf + \fBeval "$(zoxide init bash)"\fR +.fi +.TP +.B elvish +Add the following line to your configuration file (usually +\fI~/.elvish/rc.elv\fR): +.sp +.nf + \fBeval $(zoxide init elvish | slurp)\fR +.fi +.TP +.B fish +Add the following line to your configuration file (usually +\fI~/.config/fish/config.fish\fR): +.sp +.nf + \fBzoxide init fish | source\fR +.fi +.TP +.B nushell +Initialize zoxide's Nushell script: +.sp +.nf + \fBzoxide init nushell --hook prompt | save ~/.zoxide.nu\fR +.fi +.sp +Then, in your Nushell configuration file (usually +\fI~/.config/nu/config.toml\fR): +.sp +* Prepend \fB__zoxide_hook;\fR to the \fBprompt\fR variable. +.sp +* Add the following lines to the \fBstartup\fR variable: +.sp +.nf + \fBzoxide init nushell --hook prompt | save ~/.zoxide.nu + source ~/.zoxide.nu\fR +.fi +.TP +.B powershell +Add the following line to your profile: +.sp +.nf + \fBInvoke-Expression (& { + $hook = if ($PSVersionTable.PSVersion.Major -lt 6) { 'prompt' } else { 'pwd' } + (zoxide init --hook $hook powershell) -join "`n" + })\fR +.fi +.TP +.B xonsh +Add the following line to your configuration file (usually \fI~/.xonshrc\fR): +.sp +.nf + \fBexecx($(zoxide init xonsh), 'exec', __xonsh__.ctx, filename='zoxide')\fR +.fi +.TP +.B zsh +Add the following line to your configuration file (usually \fI~/.zshrc\fR): +.sp +.nf + \fBeval "$(zoxide init zsh)"\fR +.fi +.TP +.B Any POSIX shell +.sp +Add the following line to your configuration file: +.sp +.nf + \fBeval "$(zoxide init posix --hook prompt)"\fR +.fi +.SH OPTIONS +.TP +.B --cmd +Changes the prefix of predefined aliases (\fBz\fR, \fBzi\fR). +.br +e.g. --cmd j would change the aliases to j and ji respectively. +.TP +.B -h, --help +Prints help information +.TP +.B --hook \fIHOOK\fR +Changes how often zoxide increments a directory's score: +.TS +tab(|); +l l. + \fInone\fR|Never + \fIprompt\fR|At every shell prompt + \fIpwd\fR|Whenever the directory is changed +.TE +.TP +.B --no-aliases +Don't define extra aliases (\fBz\fR, \fBzi\fR). These functions will still be +available in your shell as \fB__zoxide_z\fR and \fB__zoxide_zi\fR, should you +choose to redefine them. +.SH REPORTING BUGS +For any issues, feature requests, or questions, please visit: +.sp + \fIhttps://github.com/ajeetdsouza/zoxide/issues\fR +.SH AUTHOR +Ajeet D'Souza <\fI98ajeet@gmail.com\fR> diff --git a/man/zoxide-query.1 b/man/zoxide-query.1 new file mode 100644 index 0000000..01dcd7c --- /dev/null +++ b/man/zoxide-query.1 @@ -0,0 +1,27 @@ +.TH "zoxide-query" "1" "2021-04-12" "zoxide" "zoxide" +.SH NAME +zoxide-query - search for a directory in the database +.SH SYNOPSIS +.B zoxide query \fI[KEYWORDS] [OPTIONS]\fR +.SH DESCRIPTION +Queries the database for paths matching the keywords. The exact \fBMATCHING\fR +algorithm is described in \fBzoxide\fR(1). +.SH OPTIONS +.TP +.B -h, --help +Prints help information +.TP +.B -i, --interactive +Use interactive selection. This option requires fzf. +.TP +.B -l, --list +List all results, rather than just the one with the highest frecency. +.TP +.B -s, --score +Print the calculated score as well as the matched path. +.SH REPORTING BUGS +For any issues, feature requests, or questions, please visit: +.sp + \fIhttps://github.com/ajeetdsouza/zoxide/issues\fR +.SH AUTHOR +Ajeet D'Souza <\fI98ajeet@gmail.com\fR> diff --git a/man/zoxide-remove.1 b/man/zoxide-remove.1 new file mode 100644 index 0000000..6d8192a --- /dev/null +++ b/man/zoxide-remove.1 @@ -0,0 +1,21 @@ +.TH "zoxide-remove" "1" "2021-04-12" "zoxide" "zoxide" +.SH NAME +zoxide-remove - remove a directory from the database +.SH SYNOPSIS +.B zoxide remove \fIPATH [OPTIONS]\fR +.SH DESCRIPTION +If you'd like to permanently exclude a directory from the database, see the +\fB_ZO_EXCLUDE_DIRS\fR environment variable in \fBzoxide\fR(1). +.SH OPTIONS +.TP +.B -h, --help +Prints help information +.TP +.B -i, --interactive \fI[KEYWORDS]\fR +Use interactive selection. This option requires fzf. +.SH REPORTING BUGS +For any issues, feature requests, or questions, please visit: +.sp + \fIhttps://github.com/ajeetdsouza/zoxide/issues\fR +.SH AUTHOR +Ajeet D'Souza <\fI98ajeet@gmail.com\fR> diff --git a/man/zoxide.1 b/man/zoxide.1 new file mode 100644 index 0000000..84fa168 --- /dev/null +++ b/man/zoxide.1 @@ -0,0 +1,150 @@ +.TH "zoxide" "1" "2021-04-12" "zoxide" "zoxide" +.SH NAME +zoxide - a faster way to navigate your filesystem +.SH SYNOPSIS +.B zoxide \fISUBCOMMAND [OPTIONS]\fR +.SH DESCRIPTION +zoxide is a smarter replacement for your cd command. It keeps track of the +directories you use most frequently, and uses a ranking algorithm to navigate +to the best match. +.SH USAGE + \fBz\fR \fIfoo\fR # cd into highest ranked directory matching foo + \fBz\fR \fIfoo bar\fR # cd into highest ranked directory matching foo and bar +.sp + \fBz\fR \fI~/foo\fR # z also works like a regular cd command + \fBz\fR \fIfoo/\fR # cd into relative path + \fBz\fR \fI..\fR # cd one level up + \fBz\fR \fI-\fR # cd into previous directory +.sp + \fBzi\fR \fIfoo\fR # cd with interactive selection (using fzf) +.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 +Prints help information +.TP +.B -V, --version +Prints version information +.SH ENVIRONMENT VARIABLES +Environment variables must be set before calling \fBzoxide init\fR. +.TP +.B _ZO_DATA_DIR +Specifies the directory in which zoxide should store its database. The default +value varies across OSes: +.TS +tab(|); +l l. + \fBOS|Path\fR + Linux/BSD|T{ +\fI$XDG_DATA_HOME\fR or \fI$HOME/.local/share\fR +.br +eg. /home/alice/.local/share +T} + macOS|T{ +\fI$HOME/Library/Application Support\fR +.br +eg. /Users/Alice/Library/Application Support +T} + Windows|T{ +\fI{FOLDERID_RoamingAppData}\fR +.br +eg. C:\\Users\\Alice\\AppData\\Roaming +T} +.TE +.TP +.B _ZO_ECHO +When set to \fI1\fR, z 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 + Linux/macOS/BSD|T{ +\fI:\fR eg. $HOME:$HOME/private/* +T} + Windows|\fI;\fR eg. $HOME;$HOME/private/* +.TE +.sp +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 fzf. See \fBman fzf\fR for the 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 \fI10000\fR. +.TP +.B _ZO_RESOLVE_SYMLINKS +When set to \fI1\fR, z 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 \fIk\fR such that the new total becomes ~90% of +\fB_ZO_MAXAGE\fR. Thereafter, if the new score of any directory falls below +\fI1\fR, it is removed from the database. +.sp +Theoretically, the maximum number of directories in the database is +\fI4 * _ZO_MAXAGE\fR, although it is lower in practice. +.TP +.B FRECENCY +Each directory in zoxide is given a score, starting with \fI1\fR the first time +it is accessed. Every subsequent access increases the score by \fI1\fR. 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|\fIscore * 4\fR + Within the last day|\fIscore * 2\fR + Within the last week|\fIscore / 2\fR + Otherwise|\fIscore / 4\fR +.TE +.TP +.B MATCHING +zoxide uses a simple, predictable algorithm for resolving queries: +.sp +* All matching is case-insensitive. + \fBzoxide query\fR \fIfoo\fR matches \fI/foo\fR as well as \fI/FOO\fR. +.sp +* All terms must be present (including slashes) within the path, in order. + \fBzoxide query\fR \fIfo ba\fR matches \fI/foo/bar\fR, but not \fI/bar/foo\fR. + \fBzoxide query\fR \fIfo / ba\fR matches \fI/foo/bar\fR, but not \fI/foobar\fR. +.sp +* The last component of the last keyword must match the last component of the path. + \fBzoxide query\fR \fIbar\fR matches \fI/foo/bar\fR, but not \fI/bar/foo\fR. + \fBzoxide query\fR \fIfoo/bar\fR (last component: \fIbar\fR) matches \fI/foo/bar\fR, but not \fI/foo/bar/baz\fR. +.sp +* The path must exist. Deleted directories are filtered out. +.sp +* Matches are returned in descending order of \fBFRECENCY\fR. +.SH REPORTING BUGS +For any issues, feature requests, or questions, please visit: +.sp + \fIhttps://github.com/ajeetdsouza/zoxide/issues\fR +.SH AUTHOR +Ajeet D'Souza <\fI98ajeet@gmail.com\fR> diff --git a/src/cmd/import.rs b/src/cmd/import.rs index 3b24199..44402d3 100644 --- a/src/cmd/import.rs +++ b/src/cmd/import.rs @@ -15,7 +15,7 @@ pub struct Import { path: PathBuf, /// Application to import from - #[clap(arg_enum, long, default_value = "z")] + #[clap(arg_enum, long)] from: From, /// Merge into existing database diff --git a/src/cmd/query.rs b/src/cmd/query.rs index bd7cb12..1c324d7 100644 --- a/src/cmd/query.rs +++ b/src/cmd/query.rs @@ -15,19 +15,19 @@ use std::io::{self, Write}; pub struct Query { keywords: Vec, - /// Lists all matching directories + /// Use interactive selection #[clap(long, short, conflicts_with = "list")] interactive: bool, - /// Lists all matching directories + /// List all matching directories #[clap(long, short, conflicts_with = "interactive")] list: bool, - /// Prints score with results + /// Print score with results #[clap(long, short)] score: bool, - /// Excludes a path from results + /// Exclude a path from results #[clap(long, hidden = true)] exclude: Option, } diff --git a/src/cmd/remove.rs b/src/cmd/remove.rs index 8a84d9a..ed89765 100644 --- a/src/cmd/remove.rs +++ b/src/cmd/remove.rs @@ -13,6 +13,7 @@ use std::io::Write; /// Remove a directory from the database #[derive(Clap, Debug)] pub struct Remove { + // Use interactive selection #[clap(conflicts_with = "path", long, short, value_name = "keywords")] interactive: Option>, #[clap(