Add manpage (#183)

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>

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>

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>

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>

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>

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>

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

src/cmd/query.rs

@@ -15,19 +15,19 @@ use std::io::{self, Write};
 pub struct Query {
     keywords: Vec<String>,
 
-    /// 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<String>,
 }

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<Vec<String>>,
     #[clap(