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.

629
README.md
View File

@ -51,292 +51,307 @@ Read more about the matching algorithm [here][algorithm-matching].
## Installation ## Installation
### *Step 1: Install zoxide* zoxide can be installed in 4 easy steps:
zoxide runs on most major platforms. If your platform isn't listed below, 1. **Install binary**
please [open an issue][issues].
zoxide runs on most major platforms. If your platform isn't listed below,
<details> please [open an issue][issues].
<summary>Linux</summary>
<details>
To install zoxide, run this command in your terminal: <summary>Linux</summary>
```sh > The recommended way to install zoxide is via the install script:
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
Or, you can use a package manager: > ```
>
| Distribution | Repository | Instructions | > Or, you can use a package manager:
| ------------------- | ----------------------- | ---------------------------------------------------------------------------------------------- | >
| ***Any*** | **[crates.io]** | `cargo install zoxide --locked` | > | Distribution | Repository | Instructions |
| *Any* | [conda-forge] | `conda install -c conda-forge zoxide` | > | ------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------- |
| *Any* | [Linuxbrew] | `brew install zoxide` | > | ***Any*** | **[crates.io]** | `cargo install zoxide --locked` |
| Alpine Linux 3.13+ | [Alpine Linux Packages] | `apk add zoxide` | > | *Any* | [asdf] | `asdf plugin add zoxide https://github.com/nyrst/asdf-zoxide.git` <br /> `asdf install zoxide latest` |
| Arch Linux | [Arch Linux Community] | `pacman -S zoxide` | > | *Any* | [conda-forge] | `conda install -c conda-forge zoxide` |
| CentOS 7+ | [Copr] | `dnf copr enable atim/zoxide` <br /> `dnf install zoxide` | > | *Any* | [Linuxbrew] | `brew install zoxide` |
| Debian 11+ | [Debian Packages] | `apt install zoxide` | > | Alpine Linux 3.13+ | [Alpine Linux Packages] | `apk add zoxide` |
| Devuan 4.0+ | [Devuan Packages] | `apt install zoxide` | > | Arch Linux | [Arch Linux Community] | `pacman -S zoxide` |
| Fedora 32+ | [Fedora Packages] | `dnf install zoxide` | > | CentOS 7+ | [Copr] | `dnf copr enable atim/zoxide` <br /> `dnf install zoxide` |
| Gentoo | [GURU Overlay] | `eselect repository enable guru` <br /> `emerge --sync guru` <br /> `emerge app-shells/zoxide` | > | Debian 11+[^1] | [Debian Packages] | `apt install zoxide` |
| Manjaro | | `pacman -S zoxide` | > | Devuan 4.0+[^1] | [Devuan Packages] | `apt install zoxide` |
| NixOS 21.05+ | [nixpkgs] | `nix-env -iA nixpkgs.zoxide` | > | Fedora 32+ | [Fedora Packages] | `dnf install zoxide` |
| openSUSE Tumbleweed | [openSUSE Factory] | `zypper install zoxide` | > | Gentoo | [GURU Overlay] | `eselect repository enable guru` <br /> `emerge --sync guru` <br /> `emerge app-shells/zoxide` |
| Parrot OS | | `apt install zoxide` | > | Manjaro | | `pacman -S zoxide` |
| Raspbian 11+ | [Raspbian Packages] | `apt install zoxide` | > | NixOS 21.05+ | [nixpkgs] | `nix-env -iA nixpkgs.zoxide` |
| Slackware 15.0+ | [SlackBuilds] | [Instructions][slackbuilds-howto] | > | openSUSE Tumbleweed | [openSUSE Factory] | `zypper install zoxide` |
| Ubuntu 21.04+ | [Ubuntu Packages] | `apt install zoxide` | > | Parrot OS[^1] | | `apt install zoxide` |
| Void Linux | [Void Linux Packages] | `xbps-install -S zoxide` | > | Raspbian 11+[^1] | [Raspbian Packages] | `apt install zoxide` |
> | Slackware 15.0+ | [SlackBuilds] | [Instructions][slackbuilds-howto] |
</details> > | Ubuntu 21.04+[^1] | [Ubuntu Packages] | `apt install zoxide` |
> | Void Linux | [Void Linux Packages] | `xbps-install -S zoxide` |
<details>
<summary>macOS</summary> </details>
To install zoxide, use a package manager: <details>
<summary>macOS</summary>
| Repository | Instructions |
| --------------- | ------------------------------------- | > To install zoxide, use a package manager:
| **[crates.io]** | `cargo install zoxide --locked` | >
| [conda-forge] | `conda install -c conda-forge zoxide` | > | Repository | Instructions |
| [Homebrew] | `brew install zoxide` | > | --------------- | ----------------------------------------------------------------------------------------------------- |
| [MacPorts] | `port install zoxide` | > | **[crates.io]** | `cargo install zoxide --locked` |
> | **[Homebrew]** | `brew install zoxide` |
Or, run this command in your terminal: > | [asdf] | `asdf plugin add zoxide https://github.com/nyrst/asdf-zoxide.git` <br /> `asdf install zoxide latest` |
> | [conda-forge] | `conda install -c conda-forge zoxide` |
```sh > | [MacPorts] | `port install zoxide` |
curl -sS https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh | bash >
``` > Or, run this command in your terminal:
>
</details> > ```sh
> curl -sS https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh | bash
<details> > ```
<summary>Windows</summary>
</details>
To install zoxide, run this command in your command prompt:
<details>
```sh <summary>Windows</summary>
curl.exe -A "MS" https://webinstall.dev/zoxide | powershell
``` > To install zoxide, run this command in your terminal:
>
Or, you can use a package manager: > ```sh
> curl.exe -A "MS" https://webinstall.dev/zoxide | powershell
| Repository | Instructions | > ```
| --------------- | ------------------------------------- | >
| **[crates.io]** | `cargo install zoxide --locked` | > Or, you can use a package manager:
| [Chocolatey] | `choco install zoxide` | >
| [conda-forge] | `conda install -c conda-forge zoxide` | > | Repository | Instructions |
| [Scoop] | `scoop install zoxide` | > | --------------- | ------------------------------------- |
> | **[crates.io]** | `cargo install zoxide --locked` |
</details> > | [Chocolatey] | `choco install zoxide` |
> | [conda-forge] | `conda install -c conda-forge zoxide` |
<details> > | [Scoop] | `scoop install zoxide` |
<summary>BSD</summary>
</details>
To install zoxide, use a package manager:
<details>
| Distribution | Repository | Instructions | <summary>BSD</summary>
| ------------- | --------------- | ------------------------------- |
| ***Any*** | **[crates.io]** | `cargo install zoxide --locked` | > To install zoxide, use a package manager:
| DragonFly BSD | [DPorts] | `pkg install zoxide` | >
| FreeBSD | [FreshPorts] | `pkg install zoxide` | > | Distribution | Repository | Instructions |
| NetBSD | [pkgsrc] | `pkgin install zoxide` | > | ------------- | --------------- | ------------------------------- |
> | ***Any*** | **[crates.io]** | `cargo install zoxide --locked` |
</details> > | DragonFly BSD | [DPorts] | `pkg install zoxide` |
> | FreeBSD | [FreshPorts] | `pkg install zoxide` |
<details> > | NetBSD | [pkgsrc] | `pkgin install zoxide` |
<summary>Android</summary>
</details>
To install zoxide, use a package manager:
<details>
| Repository | Instructions | <summary>Android</summary>
| ---------- | -------------------- |
| [Termux] | `pkg install zoxide` | > To install zoxide, use a package manager:
>
</details> > | Repository | Instructions |
> | ---------- | -------------------- |
### *Step 2: Add zoxide to your shell* > | [Termux] | `pkg install zoxide` |
To start using zoxide, add it to your shell. </details>
<details> 2. **Setup zoxide on your shell**
<summary>Bash</summary>
To start using zoxide, add it to your shell.
Add this to your configuration (usually `~/.bashrc`):
<details>
```sh <summary>Bash</summary>
eval "$(zoxide init bash)"
``` > Add this to your configuration (usually `~/.bashrc`):
>
</details> > ```sh
> eval "$(zoxide init bash)"
<details> > ```
<summary>Elvish</summary>
</details>
Add this to your configuration (usually `~/.elvish/rc.elv`):
<details>
```sh <summary>Elvish</summary>
eval (zoxide init elvish | slurp)
``` > Add this to your configuration (usually `~/.elvish/rc.elv`):
>
> **Note** > ```sh
> zoxide only supports elvish v0.18.0 and above. > eval (zoxide init elvish | slurp)
> ```
</details> >
> **Note**
<details> > zoxide only supports elvish v0.18.0 and above.
<summary>Fish</summary>
</details>
Add this to your configuration (usually `~/.config/fish/config.fish`):
<details>
```fish <summary>Fish</summary>
zoxide init fish | source
``` > Add this to your configuration (usually `~/.config/fish/config.fish`):
>
> **Note** > ```fish
> zoxide only supports fish v3.4.0 and above. > zoxide init fish | source
> ```
</details> >
> **Note**
<details> > zoxide only supports fish v3.4.0 and above.
<summary>Nushell</summary>
</details>
Add this to your env file (find it by running `$nu.env-path` in Nushell):
<details>
```sh <summary>Nushell</summary>
zoxide init nushell | save -f ~/.zoxide.nu
``` > Add this to your env file (find it by running `$nu.env-path` in Nushell):
>
Now, add this to the end of your config file (find it by running > ```sh
`$nu.config-path` in Nushell): > zoxide init nushell | save -f ~/.zoxide.nu
> ```
```sh >
source ~/.zoxide.nu > Now, add this to the end of your config file (find it by running
``` > `$nu.config-path` in Nushell):
>
> **Note** > ```sh
> zoxide only supports Nushell v0.73.0 and above. > source ~/.zoxide.nu
> ```
</details> >
> **Note**
<details> > zoxide only supports Nushell v0.73.0 and above.
<summary>PowerShell</summary>
</details>
Add this to your configuration (find it by running `echo $profile` in
PowerShell): <details>
<summary>PowerShell</summary>
```powershell
# For zoxide v0.8.0+ > Add this to your configuration (find it by running `echo $profile` in
Invoke-Expression (& { > PowerShell):
$hook = if ($PSVersionTable.PSVersion.Major -lt 6) { 'prompt' } else { 'pwd' } >
(zoxide init --hook $hook powershell | Out-String) > - For zoxide v0.8.0+:
}) >
> ```powershell
# For older versions of zoxide > Invoke-Expression (& {
Invoke-Expression (& { > $hook = if ($PSVersionTable.PSVersion.Major -lt 6) { 'prompt' } else { 'pwd' }
$hook = if ($PSVersionTable.PSVersion.Major -lt 6) { 'prompt' } else { 'pwd' } > (zoxide init --hook $hook powershell | Out-String)
(zoxide init --hook $hook powershell) -join "`n" > })
}) > ```
``` >
> - For older versions of zoxide:
</details> >
> ```powershell
<details> > Invoke-Expression (& {
<summary>Xonsh</summary> > $hook = if ($PSVersionTable.PSVersion.Major -lt 6) { 'prompt' } else { 'pwd' }
> (zoxide init --hook $hook powershell) -join "`n"
Add this to your configuration (usually `~/.xonshrc`): > })
> ```
```python
execx($(zoxide init xonsh), 'exec', __xonsh__.ctx, filename='zoxide') </details>
```
<details>
</details> <summary>Xonsh</summary>
<details> > Add this to your configuration (usually `~/.xonshrc`):
<summary>Zsh</summary> >
> ```python
Add this to your configuration (usually `~/.zshrc`): > execx($(zoxide init xonsh), 'exec', __xonsh__.ctx, filename='zoxide')
> ```
```sh
eval "$(zoxide init zsh)" </details>
```
<details>
For completions to work, the above line must be added *after* `compinit` is <summary>Zsh</summary>
called. You may have to rebuild your cache by running
`rm ~/.zcompdump*; compinit`. > Add this to your configuration (usually `~/.zshrc`):
>
</details> > ```sh
> eval "$(zoxide init zsh)"
<details> > ```
<summary>Any POSIX shell</summary> >
> For completions to work, the above line must be added *after* `compinit` is
Add this to your configuration: > called. You may have to rebuild your completions cache by running
> `rm ~/.zcompdump*; compinit`.
```sh
eval "$(zoxide init posix --hook prompt)" </details>
```
<details>
</details> <summary>Any POSIX shell</summary>
### *Step 3: Install fzf (optional)* > Add this to your configuration:
>
[fzf] is a command-line fuzzy finder, used by zoxide for interactive selection. > ```sh
It can be installed from [here][fzf-installation]. > eval "$(zoxide init posix --hook prompt)"
> ```
> **Note**
> zoxide only supports fzf v0.33.0 and above. </details>
### *Step 4: Import your data (optional)* 3. **Install fzf** <sup>(optional)</sup>
If you currently use any of the following plugins, you may want to import [fzf] is a command-line fuzzy finder, used by zoxide for completions /
your data into zoxide: interactive selection. It can be installed from [here][fzf-installation].
<details> > **Note**
<summary>autojump</summary> > zoxide only supports fzf v0.33.0 and above.
```sh 4. **Import your data** <sup>(optional)</sup>
zoxide import --from=autojump "/path/to/autojump/db"
``` If you currently use any of these plugins, you may want to import your data
into zoxide:
The path usually varies according to your system:
<details>
| OS | Path | Example | <summary>autojump</summary>
| ------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------ |
| Linux | `$XDG_DATA_HOME/autojump/autojump.txt` or `$HOME/.local/share/autojump/autojump.txt` | `/home/alice/.local/share/autojump/autojump.txt` | > Run this command in your terminal:
| 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` | > ```sh
> zoxide import --from=autojump "/path/to/autojump/db"
</details> > ```
>
<details> > The path usually varies according to your system:
<summary>fasd / z / z.lua / zsh-z</summary> >
> | OS | Path | Example |
```sh > | ------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------ |
zoxide import --from=z "path/to/z/db" > | 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` |
The path usually varies according to your system:
</details>
| Plugin | Path |
| ---------------- | ----------------------------------------------------------------------------------- | <details>
| fasd | `$_FASD_DATA` or `$HOME/.fasd` | <summary>fasd, z, z.lua, zsh-z</summary>
| z | `$_Z_DATA` or `$HOME/.z` |
| z.lua (bash/zsh) | `$_ZL_DATA` or `$HOME/.zlua` | > Run this command in your terminal:
| 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` | > ```sh
> zoxide import --from=z "path/to/z/db"
</details> > ```
>
<details> > The path usually varies according to your system:
<summary>ZLocation</summary> >
> | Plugin | Path |
```powershell > | ---------------- | ----------------------------------------------------------------------------------- |
$db = New-TemporaryFile > | fasd | `$_FASD_DATA` or `$HOME/.fasd` |
(Get-ZLocation).GetEnumerator() | ForEach-Object { Write-Output ($_.Name+'|'+$_.Value+'|0') } | Out-File $db > | z (bash/zsh) | `$_Z_DATA` or `$HOME/.z` |
zoxide import --from=z $db > | 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` |
</details> > | zsh-z | `$ZSHZ_DATA` or `$_Z_DATA` or `$HOME/.z` |
</details>
<details>
<summary>ZLocation</summary>
> 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
> ```
</details>
## Configuration ## Configuration
@ -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.
@ -398,26 +413,33 @@ 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 |
| [joshuto] | File manager | Natively supported | | [joshuto] | File manager | Natively supported |
| [lf] | File manager | See the [wiki][lf-wiki] | | [lf] | File manager | See the [wiki][lf-wiki] |
| [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] |
| [vim] / [neovim] | Text editor | [zoxide.vim] | | [tmux-session-wizard] | Jump to a directory inside a Tmux session | Natively supported |
| [xplr] | File manager | [zoxide.xplr] | | [vim] / [neovim] | Text editor | [zoxide.vim] |
| [xxh] | Transports shell configuration over SSH | [xxh-plugin-prerun-zoxide] | | [xplr] | File manager | [zoxide.xplr] |
| [zabb] | Finds the shortest possible query for a path | Natively supported | | [xxh] | Transports shell configuration over SSH | [xxh-plugin-prerun-zoxide] |
| [zsh-autocomplete] | Realtime completions for zsh | Natively supported | | [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-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