Llewellyn/zoxide
1
0
Fork 0
mirror of https://github.com/Llewellynvdm/zoxide.git synced 2024-11-22 12:55:13 +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
- 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.

629
README.md
View File

@ -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].
<details>
<summary>Linux</summary>
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` <br /> `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` <br /> `emerge --sync guru` <br /> `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` |
</details>
<details>
<summary>macOS</summary>
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
```
</details>
<details>
<summary>Windows</summary>
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` |
</details>
<details>
<summary>BSD</summary>
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` |
</details>
<details>
<summary>Android</summary>
To install zoxide, use a package manager:
| Repository | Instructions |
| ---------- | -------------------- |
| [Termux] | `pkg install zoxide` |
</details>
### *Step 2: Add zoxide to your shell*
To start using zoxide, add it to your shell.
<details>
<summary>Bash</summary>
Add this to your configuration (usually `~/.bashrc`):
```sh
eval "$(zoxide init bash)"
```
</details>
<details>
<summary>Elvish</summary>
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.
</details>
<details>
<summary>Fish</summary>
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.
</details>
<details>
<summary>Nushell</summary>
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.
</details>
<details>
<summary>PowerShell</summary>
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"
})
```
</details>
<details>
<summary>Xonsh</summary>
Add this to your configuration (usually `~/.xonshrc`):
```python
execx($(zoxide init xonsh), 'exec', __xonsh__.ctx, filename='zoxide')
```
</details>
<details>
<summary>Zsh</summary>
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`.
</details>
<details>
<summary>Any POSIX shell</summary>
Add this to your configuration:
```sh
eval "$(zoxide init posix --hook prompt)"
```
</details>
### *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:
<details>
<summary>autojump</summary>
```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` |
</details>
<details>
<summary>fasd / z / z.lua / zsh-z</summary>
```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` |
</details>
<details>
<summary>ZLocation</summary>
```powershell
$db = New-TemporaryFile
(Get-ZLocation).GetEnumerator() | ForEach-Object { Write-Output ($_.Name+'|'+$_.Value+'|0') } | Out-File $db
zoxide import --from=z $db
```
</details>
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].
<details>
<summary>Linux</summary>
> 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` <br /> `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` <br /> `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` <br /> `emerge --sync guru` <br /> `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` |
</details>
<details>
<summary>macOS</summary>
> 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` <br /> `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
> ```
</details>
<details>
<summary>Windows</summary>
> 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` |
</details>
<details>
<summary>BSD</summary>
> 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` |
</details>
<details>
<summary>Android</summary>
> To install zoxide, use a package manager:
>
> | Repository | Instructions |
> | ---------- | -------------------- |
> | [Termux] | `pkg install zoxide` |
</details>
2. **Setup zoxide on your shell**
To start using zoxide, add it to your shell.
<details>
<summary>Bash</summary>
> Add this to your configuration (usually `~/.bashrc`):
>
> ```sh
> eval "$(zoxide init bash)"
> ```
</details>
<details>
<summary>Elvish</summary>
> 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.
</details>
<details>
<summary>Fish</summary>
> 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.
</details>
<details>
<summary>Nushell</summary>
> 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.
</details>
<details>
<summary>PowerShell</summary>
> 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"
> })
> ```
</details>
<details>
<summary>Xonsh</summary>
> Add this to your configuration (usually `~/.xonshrc`):
>
> ```python
> execx($(zoxide init xonsh), 'exec', __xonsh__.ctx, filename='zoxide')
> ```
</details>
<details>
<summary>Zsh</summary>
> 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`.
</details>
<details>
<summary>Any POSIX shell</summary>
> Add this to your configuration:
>
> ```sh
> eval "$(zoxide init posix --hook prompt)"
> ```
</details>
3. **Install fzf** <sup>(optional)</sup>
[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** <sup>(optional)</sup>
If you currently use any of these plugins, you may want to import your data
into zoxide:
<details>
<summary>autojump</summary>
> 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` |
</details>
<details>
<summary>fasd, z, z.lua, zsh-z</summary>
> 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` |
</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
@ -362,8 +377,8 @@ When calling `zoxide init`, the following flags are available:
### Environment variables
Environment variables<sup>[?][wiki-env]</sup> 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