From 7299e33a80a997d8e899e729d98637dbbf236d9c Mon Sep 17 00:00:00 2001 From: Ajeet D'Souza <98ajeet@gmail.com> Date: Thu, 26 Jan 2023 22:35:43 +0530 Subject: [PATCH] Update README --- CHANGELOG.md | 2 +- README.md | 629 ++++++++++++++++++++++++++------------------------- 2 files changed, 327 insertions(+), 304 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index bc783e3..46be75f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -59,7 +59,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Fixed -- Bash/Fish/Posix/Zsh: paths on Cygwin. +- Bash/Fish/POSIX/Zsh: paths on Cygwin. - Fish: completions not working on certain systems. - Bash: completions not escaping spaces correctly. diff --git a/README.md b/README.md index c910124..819f37f 100644 --- a/README.md +++ b/README.md @@ -51,292 +51,307 @@ Read more about the matching algorithm [here][algorithm-matching]. ## Installation -### *Step 1: Install zoxide* - -zoxide runs on most major platforms. If your platform isn't listed below, -please [open an issue][issues]. - -
-Linux - -To install zoxide, run this command in your terminal: - -```sh -curl -sS https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh | bash -``` - -Or, you can use a package manager: - -| Distribution | Repository | Instructions | -| ------------------- | ----------------------- | ---------------------------------------------------------------------------------------------- | -| ***Any*** | **[crates.io]** | `cargo install zoxide --locked` | -| *Any* | [conda-forge] | `conda install -c conda-forge zoxide` | -| *Any* | [Linuxbrew] | `brew install zoxide` | -| Alpine Linux 3.13+ | [Alpine Linux Packages] | `apk add zoxide` | -| Arch Linux | [Arch Linux Community] | `pacman -S zoxide` | -| CentOS 7+ | [Copr] | `dnf copr enable atim/zoxide`
`dnf install zoxide` | -| Debian 11+ | [Debian Packages] | `apt install zoxide` | -| Devuan 4.0+ | [Devuan Packages] | `apt install zoxide` | -| Fedora 32+ | [Fedora Packages] | `dnf install zoxide` | -| Gentoo | [GURU Overlay] | `eselect repository enable guru`
`emerge --sync guru`
`emerge app-shells/zoxide` | -| Manjaro | | `pacman -S zoxide` | -| NixOS 21.05+ | [nixpkgs] | `nix-env -iA nixpkgs.zoxide` | -| openSUSE Tumbleweed | [openSUSE Factory] | `zypper install zoxide` | -| Parrot OS | | `apt install zoxide` | -| Raspbian 11+ | [Raspbian Packages] | `apt install zoxide` | -| Slackware 15.0+ | [SlackBuilds] | [Instructions][slackbuilds-howto] | -| Ubuntu 21.04+ | [Ubuntu Packages] | `apt install zoxide` | -| Void Linux | [Void Linux Packages] | `xbps-install -S zoxide` | - -
- -
-macOS - -To install zoxide, use a package manager: - -| Repository | Instructions | -| --------------- | ------------------------------------- | -| **[crates.io]** | `cargo install zoxide --locked` | -| [conda-forge] | `conda install -c conda-forge zoxide` | -| [Homebrew] | `brew install zoxide` | -| [MacPorts] | `port install zoxide` | - -Or, run this command in your terminal: - -```sh -curl -sS https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh | bash -``` - -
- -
-Windows - -To install zoxide, run this command in your command prompt: - -```sh -curl.exe -A "MS" https://webinstall.dev/zoxide | powershell -``` - -Or, you can use a package manager: - -| Repository | Instructions | -| --------------- | ------------------------------------- | -| **[crates.io]** | `cargo install zoxide --locked` | -| [Chocolatey] | `choco install zoxide` | -| [conda-forge] | `conda install -c conda-forge zoxide` | -| [Scoop] | `scoop install zoxide` | - -
- -
-BSD - -To install zoxide, use a package manager: - -| Distribution | Repository | Instructions | -| ------------- | --------------- | ------------------------------- | -| ***Any*** | **[crates.io]** | `cargo install zoxide --locked` | -| DragonFly BSD | [DPorts] | `pkg install zoxide` | -| FreeBSD | [FreshPorts] | `pkg install zoxide` | -| NetBSD | [pkgsrc] | `pkgin install zoxide` | - -
- -
-Android - -To install zoxide, use a package manager: - -| Repository | Instructions | -| ---------- | -------------------- | -| [Termux] | `pkg install zoxide` | - -
- -### *Step 2: Add zoxide to your shell* - -To start using zoxide, add it to your shell. - -
-Bash - -Add this to your configuration (usually `~/.bashrc`): - -```sh -eval "$(zoxide init bash)" -``` - -
- -
-Elvish - -Add this to your configuration (usually `~/.elvish/rc.elv`): - -```sh -eval (zoxide init elvish | slurp) -``` - -> **Note** -> zoxide only supports elvish v0.18.0 and above. - -
- -
-Fish - -Add this to your configuration (usually `~/.config/fish/config.fish`): - -```fish -zoxide init fish | source -``` - -> **Note** -> zoxide only supports fish v3.4.0 and above. - -
- -
-Nushell - -Add this to your env file (find it by running `$nu.env-path` in Nushell): - -```sh -zoxide init nushell | save -f ~/.zoxide.nu -``` - -Now, add this to the end of your config file (find it by running -`$nu.config-path` in Nushell): - -```sh -source ~/.zoxide.nu -``` - -> **Note** -> zoxide only supports Nushell v0.73.0 and above. - -
- -
-PowerShell - -Add this to your configuration (find it by running `echo $profile` in -PowerShell): - -```powershell -# For zoxide v0.8.0+ -Invoke-Expression (& { - $hook = if ($PSVersionTable.PSVersion.Major -lt 6) { 'prompt' } else { 'pwd' } - (zoxide init --hook $hook powershell | Out-String) -}) - -# For older versions of zoxide -Invoke-Expression (& { - $hook = if ($PSVersionTable.PSVersion.Major -lt 6) { 'prompt' } else { 'pwd' } - (zoxide init --hook $hook powershell) -join "`n" -}) -``` - -
- -
-Xonsh - -Add this to your configuration (usually `~/.xonshrc`): - -```python -execx($(zoxide init xonsh), 'exec', __xonsh__.ctx, filename='zoxide') -``` - -
- -
-Zsh - -Add this to your configuration (usually `~/.zshrc`): - -```sh -eval "$(zoxide init zsh)" -``` - -For completions to work, the above line must be added *after* `compinit` is -called. You may have to rebuild your cache by running -`rm ~/.zcompdump*; compinit`. - -
- -
-Any POSIX shell - -Add this to your configuration: - -```sh -eval "$(zoxide init posix --hook prompt)" -``` - -
- -### *Step 3: Install fzf (optional)* - -[fzf] is a command-line fuzzy finder, used by zoxide for interactive selection. -It can be installed from [here][fzf-installation]. - -> **Note** -> zoxide only supports fzf v0.33.0 and above. - -### *Step 4: Import your data (optional)* - -If you currently use any of the following plugins, you may want to import -your data into zoxide: - -
-autojump - -```sh -zoxide import --from=autojump "/path/to/autojump/db" -``` - -The path usually varies according to your system: - -| OS | Path | Example | -| ------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------ | -| Linux | `$XDG_DATA_HOME/autojump/autojump.txt` or `$HOME/.local/share/autojump/autojump.txt` | `/home/alice/.local/share/autojump/autojump.txt` | -| macOS | `$HOME/Library/autojump/autojump.txt` | `/Users/Alice/Library/autojump/autojump.txt` | -| Windows | `%APPDATA%\autojump\autojump.txt` | `C:\Users\Alice\AppData\Roaming\autojump\autojump.txt` | - -
- -
-fasd / z / z.lua / zsh-z - -```sh -zoxide import --from=z "path/to/z/db" -``` - -The path usually varies according to your system: - -| Plugin | Path | -| ---------------- | ----------------------------------------------------------------------------------- | -| fasd | `$_FASD_DATA` or `$HOME/.fasd` | -| z | `$_Z_DATA` or `$HOME/.z` | -| z.lua (bash/zsh) | `$_ZL_DATA` or `$HOME/.zlua` | -| z.lua (fish) | `$XDG_DATA_HOME/zlua/zlua.txt` or `$HOME/.local/share/zlua/zlua.txt` or `$_ZL_DATA` | -| zsh-z | `$ZSHZ_DATA` or `$_Z_DATA` or `$HOME/.z` | - -
- -
-ZLocation - -```powershell -$db = New-TemporaryFile -(Get-ZLocation).GetEnumerator() | ForEach-Object { Write-Output ($_.Name+'|'+$_.Value+'|0') } | Out-File $db -zoxide import --from=z $db -``` - -
+zoxide can be installed in 4 easy steps: + +1. **Install binary** + + zoxide runs on most major platforms. If your platform isn't listed below, + please [open an issue][issues]. + +
+ Linux + + > The recommended way to install zoxide is via the install script: + > + > ```sh + > curl -sS https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh | bash + > ``` + > + > Or, you can use a package manager: + > + > | Distribution | Repository | Instructions | + > | ------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------- | + > | ***Any*** | **[crates.io]** | `cargo install zoxide --locked` | + > | *Any* | [asdf] | `asdf plugin add zoxide https://github.com/nyrst/asdf-zoxide.git`
`asdf install zoxide latest` | + > | *Any* | [conda-forge] | `conda install -c conda-forge zoxide` | + > | *Any* | [Linuxbrew] | `brew install zoxide` | + > | Alpine Linux 3.13+ | [Alpine Linux Packages] | `apk add zoxide` | + > | Arch Linux | [Arch Linux Community] | `pacman -S zoxide` | + > | CentOS 7+ | [Copr] | `dnf copr enable atim/zoxide`
`dnf install zoxide` | + > | Debian 11+[^1] | [Debian Packages] | `apt install zoxide` | + > | Devuan 4.0+[^1] | [Devuan Packages] | `apt install zoxide` | + > | Fedora 32+ | [Fedora Packages] | `dnf install zoxide` | + > | Gentoo | [GURU Overlay] | `eselect repository enable guru`
`emerge --sync guru`
`emerge app-shells/zoxide` | + > | Manjaro | | `pacman -S zoxide` | + > | NixOS 21.05+ | [nixpkgs] | `nix-env -iA nixpkgs.zoxide` | + > | openSUSE Tumbleweed | [openSUSE Factory] | `zypper install zoxide` | + > | Parrot OS[^1] | | `apt install zoxide` | + > | Raspbian 11+[^1] | [Raspbian Packages] | `apt install zoxide` | + > | Slackware 15.0+ | [SlackBuilds] | [Instructions][slackbuilds-howto] | + > | Ubuntu 21.04+[^1] | [Ubuntu Packages] | `apt install zoxide` | + > | Void Linux | [Void Linux Packages] | `xbps-install -S zoxide` | + +
+ +
+ macOS + + > To install zoxide, use a package manager: + > + > | Repository | Instructions | + > | --------------- | ----------------------------------------------------------------------------------------------------- | + > | **[crates.io]** | `cargo install zoxide --locked` | + > | **[Homebrew]** | `brew install zoxide` | + > | [asdf] | `asdf plugin add zoxide https://github.com/nyrst/asdf-zoxide.git`
`asdf install zoxide latest` | + > | [conda-forge] | `conda install -c conda-forge zoxide` | + > | [MacPorts] | `port install zoxide` | + > + > Or, run this command in your terminal: + > + > ```sh + > curl -sS https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh | bash + > ``` + +
+ +
+ Windows + + > To install zoxide, run this command in your terminal: + > + > ```sh + > curl.exe -A "MS" https://webinstall.dev/zoxide | powershell + > ``` + > + > Or, you can use a package manager: + > + > | Repository | Instructions | + > | --------------- | ------------------------------------- | + > | **[crates.io]** | `cargo install zoxide --locked` | + > | [Chocolatey] | `choco install zoxide` | + > | [conda-forge] | `conda install -c conda-forge zoxide` | + > | [Scoop] | `scoop install zoxide` | + +
+ +
+ BSD + + > To install zoxide, use a package manager: + > + > | Distribution | Repository | Instructions | + > | ------------- | --------------- | ------------------------------- | + > | ***Any*** | **[crates.io]** | `cargo install zoxide --locked` | + > | DragonFly BSD | [DPorts] | `pkg install zoxide` | + > | FreeBSD | [FreshPorts] | `pkg install zoxide` | + > | NetBSD | [pkgsrc] | `pkgin install zoxide` | + +
+ +
+ Android + + > To install zoxide, use a package manager: + > + > | Repository | Instructions | + > | ---------- | -------------------- | + > | [Termux] | `pkg install zoxide` | + +
+ +2. **Setup zoxide on your shell** + + To start using zoxide, add it to your shell. + +
+ Bash + + > Add this to your configuration (usually `~/.bashrc`): + > + > ```sh + > eval "$(zoxide init bash)" + > ``` + +
+ +
+ Elvish + + > Add this to your configuration (usually `~/.elvish/rc.elv`): + > + > ```sh + > eval (zoxide init elvish | slurp) + > ``` + > + > **Note** + > zoxide only supports elvish v0.18.0 and above. + +
+ +
+ Fish + + > Add this to your configuration (usually `~/.config/fish/config.fish`): + > + > ```fish + > zoxide init fish | source + > ``` + > + > **Note** + > zoxide only supports fish v3.4.0 and above. + +
+ +
+ Nushell + + > Add this to your env file (find it by running `$nu.env-path` in Nushell): + > + > ```sh + > zoxide init nushell | save -f ~/.zoxide.nu + > ``` + > + > Now, add this to the end of your config file (find it by running + > `$nu.config-path` in Nushell): + > + > ```sh + > source ~/.zoxide.nu + > ``` + > + > **Note** + > zoxide only supports Nushell v0.73.0 and above. + +
+ +
+ PowerShell + + > Add this to your configuration (find it by running `echo $profile` in + > PowerShell): + > + > - For zoxide v0.8.0+: + > + > ```powershell + > Invoke-Expression (& { + > $hook = if ($PSVersionTable.PSVersion.Major -lt 6) { 'prompt' } else { 'pwd' } + > (zoxide init --hook $hook powershell | Out-String) + > }) + > ``` + > + > - For older versions of zoxide: + > + > ```powershell + > Invoke-Expression (& { + > $hook = if ($PSVersionTable.PSVersion.Major -lt 6) { 'prompt' } else { 'pwd' } + > (zoxide init --hook $hook powershell) -join "`n" + > }) + > ``` + +
+ +
+ Xonsh + + > Add this to your configuration (usually `~/.xonshrc`): + > + > ```python + > execx($(zoxide init xonsh), 'exec', __xonsh__.ctx, filename='zoxide') + > ``` + +
+ +
+ Zsh + + > Add this to your configuration (usually `~/.zshrc`): + > + > ```sh + > eval "$(zoxide init zsh)" + > ``` + > + > For completions to work, the above line must be added *after* `compinit` is + > called. You may have to rebuild your completions cache by running + > `rm ~/.zcompdump*; compinit`. + +
+ +
+ Any POSIX shell + + > Add this to your configuration: + > + > ```sh + > eval "$(zoxide init posix --hook prompt)" + > ``` + +
+ +3. **Install fzf** (optional) + + [fzf] is a command-line fuzzy finder, used by zoxide for completions / + interactive selection. It can be installed from [here][fzf-installation]. + + > **Note** + > zoxide only supports fzf v0.33.0 and above. + +4. **Import your data** (optional) + + If you currently use any of these plugins, you may want to import your data + into zoxide: + +
+ autojump + + > Run this command in your terminal: + > + > ```sh + > zoxide import --from=autojump "/path/to/autojump/db" + > ``` + > + > The path usually varies according to your system: + > + > | OS | Path | Example | + > | ------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------ | + > | Linux | `$XDG_DATA_HOME/autojump/autojump.txt` or `$HOME/.local/share/autojump/autojump.txt` | `/home/alice/.local/share/autojump/autojump.txt` | + > | macOS | `$HOME/Library/autojump/autojump.txt` | `/Users/Alice/Library/autojump/autojump.txt` | + > | Windows | `%APPDATA%\autojump\autojump.txt` | `C:\Users\Alice\AppData\Roaming\autojump\autojump.txt` | + +
+ +
+ fasd, z, z.lua, zsh-z + + > Run this command in your terminal: + > + > ```sh + > zoxide import --from=z "path/to/z/db" + > ``` + > + > The path usually varies according to your system: + > + > | Plugin | Path | + > | ---------------- | ----------------------------------------------------------------------------------- | + > | fasd | `$_FASD_DATA` or `$HOME/.fasd` | + > | z (bash/zsh) | `$_Z_DATA` or `$HOME/.z` | + > | z (fish) | `$Z_DATA` or `$XDG_DATA_HOME/z/data` or `$HOME/.local/share/z/data` | + > | z.lua (bash/zsh) | `$_ZL_DATA` or `$HOME/.zlua` | + > | z.lua (fish) | `$XDG_DATA_HOME/zlua/zlua.txt` or `$HOME/.local/share/zlua/zlua.txt` or `$_ZL_DATA` | + > | zsh-z | `$ZSHZ_DATA` or `$_Z_DATA` or `$HOME/.z` | + +
+ +
+ ZLocation + + > Run this command in PowerShell: + > + > ```powershell + > $db = New-TemporaryFile + > (Get-ZLocation).GetEnumerator() | ForEach-Object { Write-Output ($_.Name+'|'+$_.Value+'|0') } | Out-File $db + > zoxide import --from=z $db + > ``` + +
## Configuration @@ -362,8 +377,8 @@ When calling `zoxide init`, the following flags are available: ### Environment variables -Environment variables[?][wiki-env] can be used for configuration. -They must be set before `zoxide init` is called. +Environment variables[^2] can be used for configuration. They must be set before +`zoxide init` is called. - `_ZO_DATA_DIR` - Specifies the directory in which the database is stored. @@ -398,26 +413,33 @@ They must be set before `zoxide init` is called. ## Third-party integrations -| Application | Description | Plugin | -| ------------------ | -------------------------------------------- | -------------------------- | -| [clink] | Improved cmd.exe for Windows | [clink-zoxide] | -| [emacs] | Text editor | [zoxide.el] | -| [felix] | File manager | Natively supported | -| [joshuto] | File manager | Natively supported | -| [lf] | File manager | See the [wiki][lf-wiki] | -| [nnn] | File manager | [nnn-autojump] | -| [ranger] | File manager | [ranger-zoxide] | -| [telescope.nvim] | Fuzzy finder for Neovim | [telescope-zoxide] | -| [vim] / [neovim] | Text editor | [zoxide.vim] | -| [xplr] | File manager | [zoxide.xplr] | -| [xxh] | Transports shell configuration over SSH | [xxh-plugin-prerun-zoxide] | -| [zabb] | Finds the shortest possible query for a path | Natively supported | -| [zsh-autocomplete] | Realtime completions for zsh | Natively supported | +| Application | Description | Plugin | +| --------------------- | -------------------------------------------- | -------------------------- | +| [clink] | Improved cmd.exe for Windows | [clink-zoxide] | +| [emacs] | Text editor | [zoxide.el] | +| [felix] | File manager | Natively supported | +| [joshuto] | File manager | Natively supported | +| [lf] | File manager | See the [wiki][lf-wiki] | +| [nnn] | File manager | [nnn-autojump] | +| [ranger] | File manager | [ranger-zoxide] | +| [telescope.nvim] | Fuzzy finder for Neovim | [telescope-zoxide] | +| [tmux-session-wizard] | Jump to a directory inside a Tmux session | Natively supported | +| [vim] / [neovim] | Text editor | [zoxide.vim] | +| [xplr] | File manager | [zoxide.xplr] | +| [xxh] | Transports shell configuration over SSH | [xxh-plugin-prerun-zoxide] | +| [zabb] | Finds the shortest possible query for a path | Natively supported | +| [zsh-autocomplete] | Realtime completions for zsh | Natively supported | + +[^1]: Debian / Ubuntu derivatives update their packages very slowly. If you're +using one of these distributions, consider using the install script instead. +[^2]: If you're not sure how to set an environment variable on your shell, check +out the [wiki][wiki-env]. [algorithm-aging]: https://github.com/ajeetdsouza/zoxide/wiki/Algorithm#aging [algorithm-matching]: https://github.com/ajeetdsouza/zoxide/wiki/Algorithm#matching [alpine linux packages]: https://pkgs.alpinelinux.org/packages?name=zoxide [arch linux community]: https://archlinux.org/packages/community/x86_64/zoxide/ +[asdf]: https://github.com/asdf-vm/asdf [builtwithnix-badge]: https://img.shields.io/badge/builtwith-nix-7d81f7?logo=nixos&logoColor=white&style=flat-square [builtwithnix]: https://builtwithnix.org/ [chocolatey]: https://community.chocolatey.org/packages/zoxide @@ -462,6 +484,7 @@ They must be set before `zoxide init` is called. [telescope-zoxide]: https://github.com/jvgrootveld/telescope-zoxide [telescope.nvim]: https://github.com/nvim-telescope/telescope.nvim [termux]: https://github.com/termux/termux-packages/tree/master/packages/zoxide +[tmux-session-wizard]: https://github.com/27medkamal/tmux-session-wizard [tutorial]: contrib/tutorial.webp [ubuntu packages]: https://packages.ubuntu.com/jammy/zoxide [vim]: https://github.com/vim/vim