Llewellyn/zoxide
1
0
Fork 0
mirror of https://github.com/Llewellynvdm/zoxide.git synced 2024-11-25 22:17:33 +00:00
Code Issues Projects Releases Wiki Activity

Update README

Browse Source
This commit is contained in:
Ajeet D'Souza 2023-01-26 22:35:43 +05:30
parent 1c651bf8cd
commit 7299e33a80
2 changed files with 327 additions and 304 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
CHANGELOG.md
View File

@ -59,7 +59,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Fixed ### Fixed
- Bash/Fish/Posix/Zsh: paths on Cygwin. - Bash/Fish/POSIX/Zsh: paths on Cygwin.
- Fish: completions not working on certain systems. - Fish: completions not working on certain systems.
- Bash: completions not escaping spaces correctly. - Bash: completions not escaping spaces correctly.

373
README.md
View File

@ -51,7 +51,9 @@ Read more about the matching algorithm [here][algorithm-matching].
## Installation ## Installation
### *Step 1: Install zoxide* zoxide can be installed in 4 easy steps:
1. **Install binary**
zoxide runs on most major platforms. If your platform isn't listed below, zoxide runs on most major platforms. If your platform isn't listed below,
please [open an issue][issues]. please [open an issue][issues].
@ -59,126 +61,128 @@ please [open an issue][issues].
<details> <details>
<summary>Linux</summary> <summary>Linux</summary>
To install zoxide, run this command in your terminal: > The recommended way to install zoxide is via the install script:
>
```sh > ```sh
curl -sS https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh | bash > curl -sS https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh | bash
``` > ```
>
Or, you can use a package manager: > Or, you can use a package manager:
>
| Distribution | Repository | Instructions | > | Distribution | Repository | Instructions |
| ------------------- | ----------------------- | ---------------------------------------------------------------------------------------------- | > | ------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------- |
| ***Any*** | **[crates.io]** | `cargo install zoxide --locked` | > | ***Any*** | **[crates.io]** | `cargo install zoxide --locked` |
| *Any* | [conda-forge] | `conda install -c conda-forge zoxide` | > | *Any* | [asdf] | `asdf plugin add zoxide https://github.com/nyrst/asdf-zoxide.git` <br /> `asdf install zoxide latest` |
| *Any* | [Linuxbrew] | `brew install zoxide` | > | *Any* | [conda-forge] | `conda install -c conda-forge zoxide` |
| Alpine Linux 3.13+ | [Alpine Linux Packages] | `apk add zoxide` | > | *Any* | [Linuxbrew] | `brew install zoxide` |
| Arch Linux | [Arch Linux Community] | `pacman -S zoxide` | > | Alpine Linux 3.13+ | [Alpine Linux Packages] | `apk add zoxide` |
| CentOS 7+ | [Copr] | `dnf copr enable atim/zoxide` <br /> `dnf install zoxide` | > | Arch Linux | [Arch Linux Community] | `pacman -S zoxide` |
| Debian 11+ | [Debian Packages] | `apt install zoxide` | > | CentOS 7+ | [Copr] | `dnf copr enable atim/zoxide` <br /> `dnf install zoxide` |
| Devuan 4.0+ | [Devuan Packages] | `apt install zoxide` | > | Debian 11+[^1] | [Debian Packages] | `apt install zoxide` |
| Fedora 32+ | [Fedora Packages] | `dnf install zoxide` | > | Devuan 4.0+[^1] | [Devuan Packages] | `apt install zoxide` |
| Gentoo | [GURU Overlay] | `eselect repository enable guru` <br /> `emerge --sync guru` <br /> `emerge app-shells/zoxide` | > | Fedora 32+ | [Fedora Packages] | `dnf install zoxide` |
| Manjaro | | `pacman -S zoxide` | > | Gentoo | [GURU Overlay] | `eselect repository enable guru` <br /> `emerge --sync guru` <br /> `emerge app-shells/zoxide` |
| NixOS 21.05+ | [nixpkgs] | `nix-env -iA nixpkgs.zoxide` | > | Manjaro | | `pacman -S zoxide` |
| openSUSE Tumbleweed | [openSUSE Factory] | `zypper install zoxide` | > | NixOS 21.05+ | [nixpkgs] | `nix-env -iA nixpkgs.zoxide` |
| Parrot OS | | `apt install zoxide` | > | openSUSE Tumbleweed | [openSUSE Factory] | `zypper install zoxide` |
| Raspbian 11+ | [Raspbian Packages] | `apt install zoxide` | > | Parrot OS[^1] | | `apt install zoxide` |
| Slackware 15.0+ | [SlackBuilds] | [Instructions][slackbuilds-howto] | > | Raspbian 11+[^1] | [Raspbian Packages] | `apt install zoxide` |
| Ubuntu 21.04+ | [Ubuntu Packages] | `apt install zoxide` | > | Slackware 15.0+ | [SlackBuilds] | [Instructions][slackbuilds-howto] |
| Void Linux | [Void Linux Packages] | `xbps-install -S zoxide` | > | Ubuntu 21.04+[^1] | [Ubuntu Packages] | `apt install zoxide` |
> | Void Linux | [Void Linux Packages] | `xbps-install -S zoxide` |
</details> </details>
<details> <details>
<summary>macOS</summary> <summary>macOS</summary>
To install zoxide, use a package manager: > To install zoxide, use a package manager:
>
| Repository | Instructions | > | Repository | Instructions |
| --------------- | ------------------------------------- | > | --------------- | ----------------------------------------------------------------------------------------------------- |
| **[crates.io]** | `cargo install zoxide --locked` | > | **[crates.io]** | `cargo install zoxide --locked` |
| [conda-forge] | `conda install -c conda-forge zoxide` | > | **[Homebrew]** | `brew install zoxide` |
| [Homebrew] | `brew install zoxide` | > | [asdf] | `asdf plugin add zoxide https://github.com/nyrst/asdf-zoxide.git` <br /> `asdf install zoxide latest` |
| [MacPorts] | `port install zoxide` | > | [conda-forge] | `conda install -c conda-forge zoxide` |
> | [MacPorts] | `port install zoxide` |
Or, run this command in your terminal: >
> Or, run this command in your terminal:
```sh >
curl -sS https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh | bash > ```sh
``` > curl -sS https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh | bash
> ```
</details> </details>
<details> <details>
<summary>Windows</summary> <summary>Windows</summary>
To install zoxide, run this command in your command prompt: > To install zoxide, run this command in your terminal:
>
```sh > ```sh
curl.exe -A "MS" https://webinstall.dev/zoxide | powershell > curl.exe -A "MS" https://webinstall.dev/zoxide | powershell
``` > ```
>
Or, you can use a package manager: > Or, you can use a package manager:
>
| Repository | Instructions | > | Repository | Instructions |
| --------------- | ------------------------------------- | > | --------------- | ------------------------------------- |
| **[crates.io]** | `cargo install zoxide --locked` | > | **[crates.io]** | `cargo install zoxide --locked` |
| [Chocolatey] | `choco install zoxide` | > | [Chocolatey] | `choco install zoxide` |
| [conda-forge] | `conda install -c conda-forge zoxide` | > | [conda-forge] | `conda install -c conda-forge zoxide` |
| [Scoop] | `scoop install zoxide` | > | [Scoop] | `scoop install zoxide` |
</details> </details>
<details> <details>
<summary>BSD</summary> <summary>BSD</summary>
To install zoxide, use a package manager: > To install zoxide, use a package manager:
>
| Distribution | Repository | Instructions | > | Distribution | Repository | Instructions |
| ------------- | --------------- | ------------------------------- | > | ------------- | --------------- | ------------------------------- |
| ***Any*** | **[crates.io]** | `cargo install zoxide --locked` | > | ***Any*** | **[crates.io]** | `cargo install zoxide --locked` |
| DragonFly BSD | [DPorts] | `pkg install zoxide` | > | DragonFly BSD | [DPorts] | `pkg install zoxide` |
| FreeBSD | [FreshPorts] | `pkg install zoxide` | > | FreeBSD | [FreshPorts] | `pkg install zoxide` |
| NetBSD | [pkgsrc] | `pkgin install zoxide` | > | NetBSD | [pkgsrc] | `pkgin install zoxide` |
</details> </details>
<details> <details>
<summary>Android</summary> <summary>Android</summary>
To install zoxide, use a package manager: > To install zoxide, use a package manager:
>
| Repository | Instructions | > | Repository | Instructions |
| ---------- | -------------------- | > | ---------- | -------------------- |
| [Termux] | `pkg install zoxide` | > | [Termux] | `pkg install zoxide` |
</details> </details>
### *Step 2: Add zoxide to your shell* 2. **Setup zoxide on your shell**
To start using zoxide, add it to your shell. To start using zoxide, add it to your shell.
<details> <details>
<summary>Bash</summary> <summary>Bash</summary>
Add this to your configuration (usually `~/.bashrc`): > Add this to your configuration (usually `~/.bashrc`):
>
```sh > ```sh
eval "$(zoxide init bash)" > eval "$(zoxide init bash)"
``` > ```
</details> </details>
<details> <details>
<summary>Elvish</summary> <summary>Elvish</summary>
Add this to your configuration (usually `~/.elvish/rc.elv`): > Add this to your configuration (usually `~/.elvish/rc.elv`):
>
```sh > ```sh
eval (zoxide init elvish | slurp) > eval (zoxide init elvish | slurp)
``` > ```
>
> **Note** > **Note**
> zoxide only supports elvish v0.18.0 and above. > zoxide only supports elvish v0.18.0 and above.
@ -187,12 +191,12 @@ eval (zoxide init elvish | slurp)
<details> <details>
<summary>Fish</summary> <summary>Fish</summary>
Add this to your configuration (usually `~/.config/fish/config.fish`): > Add this to your configuration (usually `~/.config/fish/config.fish`):
>
```fish > ```fish
zoxide init fish | source > zoxide init fish | source
``` > ```
>
> **Note** > **Note**
> zoxide only supports fish v3.4.0 and above. > zoxide only supports fish v3.4.0 and above.
@ -201,19 +205,19 @@ zoxide init fish | source
<details> <details>
<summary>Nushell</summary> <summary>Nushell</summary>
Add this to your env file (find it by running `$nu.env-path` in Nushell): > Add this to your env file (find it by running `$nu.env-path` in Nushell):
>
```sh > ```sh
zoxide init nushell | save -f ~/.zoxide.nu > zoxide init nushell | save -f ~/.zoxide.nu
``` > ```
>
Now, add this to the end of your config file (find it by running > Now, add this to the end of your config file (find it by running
`$nu.config-path` in Nushell): > `$nu.config-path` in Nushell):
>
```sh > ```sh
source ~/.zoxide.nu > source ~/.zoxide.nu
``` > ```
>
> **Note** > **Note**
> zoxide only supports Nushell v0.73.0 and above. > zoxide only supports Nushell v0.73.0 and above.
@ -222,119 +226,130 @@ source ~/.zoxide.nu
<details> <details>
<summary>PowerShell</summary> <summary>PowerShell</summary>
Add this to your configuration (find it by running `echo $profile` in > Add this to your configuration (find it by running `echo $profile` in
PowerShell): > PowerShell):
>
```powershell > - For zoxide v0.8.0+:
# For zoxide v0.8.0+ >
Invoke-Expression (& { > ```powershell
$hook = if ($PSVersionTable.PSVersion.Major -lt 6) { 'prompt' } else { 'pwd' } > Invoke-Expression (& {
(zoxide init --hook $hook powershell | Out-String) > $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' } > - For older versions of zoxide:
(zoxide init --hook $hook powershell) -join "`n" >
}) > ```powershell
``` > Invoke-Expression (& {
> $hook = if ($PSVersionTable.PSVersion.Major -lt 6) { 'prompt' } else { 'pwd' }
> (zoxide init --hook $hook powershell) -join "`n"
> })
> ```
</details> </details>
<details> <details>
<summary>Xonsh</summary> <summary>Xonsh</summary>
Add this to your configuration (usually `~/.xonshrc`): > Add this to your configuration (usually `~/.xonshrc`):
>
```python > ```python
execx($(zoxide init xonsh), 'exec', __xonsh__.ctx, filename='zoxide') > execx($(zoxide init xonsh), 'exec', __xonsh__.ctx, filename='zoxide')
``` > ```
</details> </details>
<details> <details>
<summary>Zsh</summary> <summary>Zsh</summary>
Add this to your configuration (usually `~/.zshrc`): > Add this to your configuration (usually `~/.zshrc`):
>
```sh > ```sh
eval "$(zoxide init zsh)" > eval "$(zoxide init zsh)"
``` > ```
>
For completions to work, the above line must be added *after* `compinit` is > For completions to work, the above line must be added *after* `compinit` is
called. You may have to rebuild your cache by running > called. You may have to rebuild your completions cache by running
`rm ~/.zcompdump*; compinit`. > `rm ~/.zcompdump*; compinit`.
</details> </details>
<details> <details>
<summary>Any POSIX shell</summary> <summary>Any POSIX shell</summary>
Add this to your configuration: > Add this to your configuration:
>
```sh > ```sh
eval "$(zoxide init posix --hook prompt)" > eval "$(zoxide init posix --hook prompt)"
``` > ```
</details> </details>
### *Step 3: Install fzf (optional)* 3. **Install fzf** <sup>(optional)</sup>
[fzf] is a command-line fuzzy finder, used by zoxide for interactive selection. [fzf] is a command-line fuzzy finder, used by zoxide for completions /
It can be installed from [here][fzf-installation]. interactive selection. It can be installed from [here][fzf-installation].
> **Note** > **Note**
> zoxide only supports fzf v0.33.0 and above. > zoxide only supports fzf v0.33.0 and above.
### *Step 4: Import your data (optional)* 4. **Import your data** <sup>(optional)</sup>
If you currently use any of the following plugins, you may want to import If you currently use any of these plugins, you may want to import your data
your data into zoxide: into zoxide:
<details> <details>
<summary>autojump</summary> <summary>autojump</summary>
```sh > Run this command in your terminal:
zoxide import --from=autojump "/path/to/autojump/db" >
``` > ```sh
> zoxide import --from=autojump "/path/to/autojump/db"
The path usually varies according to your system: > ```
>
| OS | Path | Example | > The path usually varies according to your system:
| ------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------ | >
| Linux | `$XDG_DATA_HOME/autojump/autojump.txt` or `$HOME/.local/share/autojump/autojump.txt` | `/home/alice/.local/share/autojump/autojump.txt` | > | OS | Path | Example |
| 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` | > | 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` |
</details> </details>
<details> <details>
<summary>fasd / z / z.lua / zsh-z</summary> <summary>fasd, z, z.lua, zsh-z</summary>
```sh > Run this command in your terminal:
zoxide import --from=z "path/to/z/db" >
``` > ```sh
> zoxide import --from=z "path/to/z/db"
The path usually varies according to your system: > ```
>
| Plugin | Path | > The path usually varies according to your system:
| ---------------- | ----------------------------------------------------------------------------------- | >
| fasd | `$_FASD_DATA` or `$HOME/.fasd` | > | Plugin | Path |
| z | `$_Z_DATA` or `$HOME/.z` | > | ---------------- | ----------------------------------------------------------------------------------- |
| z.lua (bash/zsh) | `$_ZL_DATA` or `$HOME/.zlua` | > | fasd | `$_FASD_DATA` or `$HOME/.fasd` |
| z.lua (fish) | `$XDG_DATA_HOME/zlua/zlua.txt` or `$HOME/.local/share/zlua/zlua.txt` or `$_ZL_DATA` | > | z (bash/zsh) | `$_Z_DATA` or `$HOME/.z` |
| zsh-z | `$ZSHZ_DATA` or `$_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` |
</details> </details>
<details> <details>
<summary>ZLocation</summary> <summary>ZLocation</summary>
```powershell > Run this command in PowerShell:
$db = New-TemporaryFile >
(Get-ZLocation).GetEnumerator() | ForEach-Object { Write-Output ($_.Name+'|'+$_.Value+'|0') } | Out-File $db > ```powershell
zoxide import --from=z $db > $db = New-TemporaryFile
``` > (Get-ZLocation).GetEnumerator() | ForEach-Object { Write-Output ($_.Name+'|'+$_.Value+'|0') } | Out-File $db
> zoxide import --from=z $db
> ```
</details> </details>
@ -362,8 +377,8 @@ When calling `zoxide init`, the following flags are available:
### Environment variables ### Environment variables
Environment variables<sup>[?][wiki-env]</sup> can be used for configuration. Environment variables[^2] can be used for configuration. They must be set before
They must be set before `zoxide init` is called. `zoxide init` is called.
- `_ZO_DATA_DIR` - `_ZO_DATA_DIR`
- Specifies the directory in which the database is stored. - Specifies the directory in which the database is stored.
@ -399,7 +414,7 @@ They must be set before `zoxide init` is called.
## Third-party integrations ## Third-party integrations
| Application | Description | Plugin | | Application | Description | Plugin |
| ------------------ | -------------------------------------------- | -------------------------- | | --------------------- | -------------------------------------------- | -------------------------- |
| [clink] | Improved cmd.exe for Windows | [clink-zoxide] | | [clink] | Improved cmd.exe for Windows | [clink-zoxide] |
| [emacs] | Text editor | [zoxide.el] | | [emacs] | Text editor | [zoxide.el] |
| [felix] | File manager | Natively supported | | [felix] | File manager | Natively supported |
@ -408,16 +423,23 @@ They must be set before `zoxide init` is called.
| [nnn] | File manager | [nnn-autojump] | | [nnn] | File manager | [nnn-autojump] |
| [ranger] | File manager | [ranger-zoxide] | | [ranger] | File manager | [ranger-zoxide] |
| [telescope.nvim] | Fuzzy finder for Neovim | [telescope-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] | | [vim] / [neovim] | Text editor | [zoxide.vim] |
| [xplr] | File manager | [zoxide.xplr] | | [xplr] | File manager | [zoxide.xplr] |
| [xxh] | Transports shell configuration over SSH | [xxh-plugin-prerun-zoxide] | | [xxh] | Transports shell configuration over SSH | [xxh-plugin-prerun-zoxide] |
| [zabb] | Finds the shortest possible query for a path | Natively supported | | [zabb] | Finds the shortest possible query for a path | Natively supported |
| [zsh-autocomplete] | Realtime completions for zsh | 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-aging]: https://github.com/ajeetdsouza/zoxide/wiki/Algorithm#aging
[algorithm-matching]: https://github.com/ajeetdsouza/zoxide/wiki/Algorithm#matching [algorithm-matching]: https://github.com/ajeetdsouza/zoxide/wiki/Algorithm#matching
[alpine linux packages]: https://pkgs.alpinelinux.org/packages?name=zoxide [alpine linux packages]: https://pkgs.alpinelinux.org/packages?name=zoxide
[arch linux community]: https://archlinux.org/packages/community/x86_64/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-badge]: https://img.shields.io/badge/builtwith-nix-7d81f7?logo=nixos&logoColor=white&style=flat-square
[builtwithnix]: https://builtwithnix.org/ [builtwithnix]: https://builtwithnix.org/
[chocolatey]: https://community.chocolatey.org/packages/zoxide [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-zoxide]: https://github.com/jvgrootveld/telescope-zoxide
[telescope.nvim]: https://github.com/nvim-telescope/telescope.nvim [telescope.nvim]: https://github.com/nvim-telescope/telescope.nvim
[termux]: https://github.com/termux/termux-packages/tree/master/packages/zoxide [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 [tutorial]: contrib/tutorial.webp
[ubuntu packages]: https://packages.ubuntu.com/jammy/zoxide [ubuntu packages]: https://packages.ubuntu.com/jammy/zoxide
[vim]: https://github.com/vim/vim [vim]: https://github.com/vim/vim