Llewellyn/zoxide
1
0
Fork 0
mirror of https://github.com/Llewellynvdm/zoxide.git synced 2024-06-06 17:30:50 +00:00
Code Issues Projects Releases Wiki Activity

Add linting for manpages

Browse Source
This commit is contained in:
Ajeet D'Souza 2021-09-28 04:52:27 +05:30
parent 2f2f588595
commit 49f406e3ed
11 changed files with 118 additions and 128 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
Cargo.toml
View File

@ -37,24 +37,7 @@ clap_generate = "=3.0.0-beta.4"
[features]
default = []
# Adds tests for code generated by `zoxide init`.
# This requires the following external programs available in $PATH:
# - bash
# - black: <https://github.com/psf/black>
# - dash
# - elvish: <https://github.com/elves/elvish>
# - fish: <https://github.com/fish-shell/fish-shell>
# - mypy: <https://github.com/python/mypy>
# - nushell: <https://github.com/nushell/nushell>
# - powershell: <https://github.com/PowerShell/PowerShell>
# - pylint: <https://github.com/PyCQA/pylint>
# - shellcheck: <https://github.com/koalaman/shellcheck>
# - shfmt: <https://github.com/mvdan/sh>
# - xonsh: <https://github.com/xonsh/xonsh>
# - zsh: <https://github.com/zsh-users/zsh>
# Since most users are unlikely to have installed all of the above, these tests
# are disabled by default.
shell_tests = []
nix_tests = []
[profile.release]
codegen-units = 1

16
man/zoxide-add.1
View File

@ -1,13 +1,13 @@
.TH "zoxide-add" "1" "2021-04-12" "zoxide" "zoxide"
.TH "ZOXIDE" "1" "2021-04-12" "" "zoxide"
.SH NAME
zoxide-add - add a new directory or increment its rank
\fBzoxide-add\fR - add a new directory or increment its rank
.SH SYNOPSIS
.B zoxide add \fI[PATHS]\fR
.B zoxide add [PATHS]
.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
entry for it with a default score of 1, otherwise, it increments the existing
score by 1. 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
@ -19,6 +19,6 @@ Print help information.
.SH REPORTING BUGS
For any issues, feature requests, or questions, please visit:
.sp
\fIhttps://github.com/ajeetdsouza/zoxide/issues\fR
\fBhttps://github.com/ajeetdsouza/zoxide/issues\fR.
.SH AUTHOR
Ajeet D'Souza <\fI98ajeet@gmail.com\fR>
Ajeet D'Souza <\fB98ajeet@gmail.com\fR>

18
man/zoxide-import.1
View File

@ -1,20 +1,20 @@
.TH "zoxide-import" "1" "2021-04-12" "zoxide" "zoxide"
.TH "ZOXIDE" "1" "2021-04-12" "" "zoxide"
.SH NAME
zoxide-import - import data from other tools
\fBzoxide-import\fR - import data from other tools
.SH SYNOPSIS
.B zoxide import \fIPATH --from FORMAT [OPTIONS]\fR
.B zoxide import PATH --from FORMAT [OPTIONS]
.SH OPTIONS
.TP
.B --from \fIFORMAT\fR
.B --from FORMAT
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.
\fBautojump\fR
\fBz\fR|(for \fBz\fR, \fBz.lua\fR, or \fBzsh-z\fR)
.TE
.sp
\fBNOTE\fR: zoxide only imports paths from autojump, since its matching
Note: zoxide only imports paths from autojump, since its matching
algorithm is too different to import the scores.
.TP
.B -h, --help
@ -26,6 +26,6 @@ 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
\fBhttps://github.com/ajeetdsouza/zoxide/issues\fR.
.SH AUTHOR
Ajeet D'Souza <\fI98ajeet@gmail.com\fR>
Ajeet D'Souza <\fB98ajeet@gmail.com\fR>

29
man/zoxide-init.1
View File

@ -1,28 +1,29 @@
.TH "zoxide-init" "1" "2021-04-12" "zoxide" "zoxide"
.TH "ZOXIDE" "1" "2021-04-12" "" "zoxide"
.SH NAME
zoxide-init - generate shell configuration for zoxide
\fBzoxide-init\fR - generate shell configuration for zoxide
.SH SYNOPSIS
.B zoxide init \fISHELL [OPTIONS]\fR
.B zoxide init SHELL [OPTIONS]
.SH DESCRIPTION
To initialize zoxide on your shell:
.TP
.B bash
Add this to your configuration (usually \fI~/.bashrc\fR):
Add this to your configuration (usually \fB~/.bashrc\fR):
.sp
.nf
\fBeval "$(zoxide init bash)"\fR
.fi
.TP
.B elvish
Add this to your configuration (usually \fI~/.elvish/rc.elv\fR):
Add this to your configuration (usually \fB~/.elvish/rc.elv\fR):
.sp
.nf
\fBeval $(zoxide init elvish | slurp)\fR
.fi
.sp
Note: zoxide only supports elvish v0.16.0 and above.
.TP
.B fish
Add this to your configuration (usually \fI~/.config/fish/config.fish\fR):
Add this to your configuration (usually \fB~/.config/fish/config.fish\fR):
.sp
.nf
\fBzoxide init fish | source\fR
@ -50,14 +51,14 @@ PowerShell):
.fi
.TP
.B xonsh
Add this to your configuration (usually \fI~/.xonshrc\fR):
Add this to your configuration (usually \fB~/.xonshrc\fR):
.sp
.nf
\fBexecx($(zoxide init xonsh), 'exec', __xonsh__.ctx, filename='zoxide')\fR
.fi
.TP
.B zsh
Add this to your configuration (usually \fI~/.zshrc\fR):
Add this to your configuration (usually \fB~/.zshrc\fR):
.sp
.nf
\fBeval "$(zoxide init zsh)"\fR
@ -80,14 +81,14 @@ e.g. --cmd j would change the aliases to j and ji respectively.
.B -h, --help
Print help information.
.TP
.B --hook \fIHOOK\fR
.B --hook HOOK
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
\fBnone\fR|Never
\fBprompt\fR|At every shell prompt
\fBpwd\fR|Whenever the directory is changed
.TE
.TP
.B --no-aliases
@ -97,6 +98,6 @@ choose to redefine them.
.SH REPORTING BUGS
For any issues, feature requests, or questions, please visit:
.sp
\fIhttps://github.com/ajeetdsouza/zoxide/issues\fR
\fBhttps://github.com/ajeetdsouza/zoxide/issues\fR.
.SH AUTHOR
Ajeet D'Souza <\fI98ajeet@gmail.com\fR>
Ajeet D'Souza <\fB98ajeet@gmail.com\fR>

12
man/zoxide-query.1
View File

@ -1,8 +1,8 @@
.TH "zoxide-query" "1" "2021-04-12" "zoxide" "zoxide"
.TH "ZOXIDE" "1" "2021-04-12" "" "zoxide"
.SH NAME
zoxide-query - search for a directory in the database
\fBzoxide-query\fR - search for a directory in the database
.SH SYNOPSIS
.B zoxide query \fI[KEYWORDS] [OPTIONS]\fR
.B zoxide query [KEYWORDS] [OPTIONS]
.SH DESCRIPTION
Query the database for paths matching the keywords. The exact \fBMATCHING\fR
algorithm is described in \fBzoxide\fR(1).
@ -11,7 +11,7 @@ algorithm is described in \fBzoxide\fR(1).
.B --all
Show deleted directories.
.TP
.B --exclude \fIPATH\fR
.B --exclude PATH
Exclude a path from query results.
.TP
.B -h, --help
@ -28,6 +28,6 @@ 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
\fBhttps://github.com/ajeetdsouza/zoxide/issues\fR.
.SH AUTHOR
Ajeet D'Souza <\fI98ajeet@gmail.com\fR>
Ajeet D'Souza <\fB98ajeet@gmail.com\fR>

12
man/zoxide-remove.1
View File

@ -1,8 +1,8 @@
.TH "zoxide-remove" "1" "2021-04-12" "zoxide" "zoxide"
.TH "ZOXIDE" "1" "2021-04-12" "" "zoxide"
.SH NAME
zoxide-remove - remove a directory from the database
\fBzoxide-remove\fR - remove a directory from the database
.SH SYNOPSIS
.B zoxide remove \fI[PATHS] [OPTIONS]\fR
.B zoxide remove [PATHS] [OPTIONS]
.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).
@ -11,11 +11,11 @@ If you'd like to permanently exclude a directory from the database, see the
.B -h, --help
Print help information.
.TP
.B -i, --interactive \fI[KEYWORDS]\fR
.B -i, --interactive [KEYWORDS]
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
\fBhttps://github.com/ajeetdsouza/zoxide/issues\fR.
.SH AUTHOR
Ajeet D'Souza <\fI98ajeet@gmail.com\fR>
Ajeet D'Souza <\fB98ajeet@gmail.com\fR>

105
man/zoxide.1
View File

@ -1,23 +1,23 @@
.TH "zoxide" "1" "2021-04-12" "zoxide" "zoxide"
.TH "ZOXIDE" "1" "2021-04-12" "" "zoxide"
.SH NAME
zoxide - a smarter cd command
\fBzoxide\fR - a smarter cd command
.SH SYNOPSIS
.B zoxide \fISUBCOMMAND [OPTIONS]\fR
.B zoxide SUBCOMMAND [OPTIONS]
.SH DESCRIPTION
zoxide is a smarter replacement for your cd command. It keeps track of the
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
\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
$ z foo # cd into highest ranked directory matching foo
$ z foo bar # 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
$ 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
\fBzi\fR \fIfoo\fR # cd with interactive selection (using fzf)
$ zi foo # cd with interactive selection (using fzf)
.fi
.SH SUBCOMMANDS
.TP
@ -43,35 +43,30 @@ Print help information.
.B -V, --version
Print version information.
.SH ENVIRONMENT VARIABLES
Environment variables must be set before calling \fBzoxide init\fR.
Environment variables must be set before calling \fBzoxide-init\fR(1).
.TP
.B _ZO_DATA_DIR
Specifies the directory in which zoxide should store its database. The default
value varies across OSes:
Specifies the directory in which the database is stored. 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
\fBLinux/BSD\fR|T{
\fB$XDG_DATA_HOME\fR or \fB$HOME/.local/share\fR, eg.
\fB/home/alice/.local/share\fR
T}
macOS|T{
\fI$HOME/Library/Application Support\fR
.br
eg. /Users/Alice/Library/Application Support
\fBmacOS\fR|T{
\fB$HOME/Library/Application Support\fR, eg.
\fB/Users/Alice/Library/Application Support\fR
T}
Windows|T{
\fI{FOLDERID_RoamingAppData}\fR
.br
eg. C:\\Users\\Alice\\AppData\\Roaming
\fBWindows\fR|T{
\fB{FOLDERID_RoamingAppData}\fR, eg. \fBC:\\Users\\Alice\\AppData\\Roaming\fR
T}
.TE
.TP
.B _ZO_ECHO
When set to \fI1\fR, z will print the matched directory before navigating
to it.
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
@ -80,24 +75,24 @@ provided as a list of globs, separated by OS-specific characters:
tab(|);
l l.
\fBOS|Separator\fR
Linux/macOS/BSD|T{
\fI:\fR eg. $HOME:$HOME/private/*
\fBLinux/macOS/BSD\fR|T{
\fB:\fR, eg. \fB$HOME:$HOME/private/*\fR
T}
Windows|\fI;\fR eg. $HOME;$HOME/private/*
\fBWindows\fR|\fB;\fR, eg. \fB$HOME;$HOME/private/*\fR
.TE
.sp
By default, this is set to \fI"$HOME"\fR. After setting this up, you might need
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 fzf. See \fBman fzf\fR for the list of options.
Custom options to pass to fzf. See \fBfzf\fR(1) 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.
the database. By default, this is set to \fB10000\fR.
.TP
.B _ZO_RESOLVE_SYMLINKS
When set to \fI1\fR, z will resolve symlinks before adding directories to
When set to 1, \fBz\fR will resolve symlinks before adding directories to
the database.
.SH ALGORITHM
.TP
@ -105,48 +100,30 @@ the database.
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
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
\fI1\fR, it is removed from the database.
1, 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.
\fB4 * _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
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|\fIscore * 4\fR
Within the last day|\fIscore * 2\fR
Within the last week|\fIscore / 2\fR
Otherwise|\fIscore / 4\fR
Within the last hour|score * 4
Within the last day|score * 2
Within the last week|score / 2
Otherwise|score / 4
.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
\fBhttps://github.com/ajeetdsouza/zoxide/issues\fR.
.SH AUTHOR
Ajeet D'Souza <\fI98ajeet@gmail.com\fR>
Ajeet D'Souza <\fB98ajeet@gmail.com\fR>

3
shell.nix
View File

@ -18,8 +18,9 @@ pkgs.mkShell {
pkgs.powershell
pkgs.zsh
# Linters
# Tools
pkgs-latest.cargo-audit
pkgs-latest.mandoc
pkgs-latest.nodePackages.markdownlint-cli
pkgs-latest.python3Packages.black
pkgs-latest.python3Packages.mypy

2
src/shell.rs
View File

@ -41,7 +41,7 @@ make_template!(Powershell, "powershell.txt");
make_template!(Xonsh, "xonsh.txt");
make_template!(Zsh, "zsh.txt");
#[cfg(feature = "shell_tests")]
#[cfg(feature = "nix_tests")]
#[cfg(test)]
mod tests {
use askama::Template;

2
tests/completion.rs
View File

@ -1,6 +1,6 @@
//! Syntax checking for auto-generated shell completions.
#![cfg(feature = "nix_tests")]
#![cfg(feature = "shell_tests")]
use assert_cmd::Command;
#[test]

28
tests/man.rs Normal file
View File

@ -0,0 +1,28 @@
//! Syntax checking for manpages.
#![cfg(feature = "nix_tests")]
use assert_cmd::Command;
use std::fs;
#[test]
fn mandoc_lint() {
let paths = fs::read_dir("man")
.unwrap()
.filter_map(|entry| {
let path = entry.unwrap().path();
if path.is_file() && path.extension() == Some("1".as_ref()) {
Some(path.to_str().unwrap().to_string())
} else {
None
}
})
.collect::<Vec<_>>();
Command::new("mandoc")
.args(&["-man", "-Wall", "-Tlint", "--"])
.args(&paths)
.assert()
.success()
.stdout("")
.stderr("");
}