diff --git a/README.md b/README.md index d504a242..0732449d 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,5 @@ + + # `zoxide` > A smarter cd command for your terminal @@ -31,40 +33,49 @@ Read more about the matching algorithm [here][algorithm-matching]. ### Step 1: Install `zoxide` -On **Linux** / **macOS**: +`zoxide` supports 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://webinstall.dev/zoxide | bash ``` -On **Windows**: +Alternatively, you can use a package manager: + +| Distribution | Repository | Instructions | +| ------------------ | ----------------------- | ---------------------------------------------------------------------------------------------- | +| ***Any*** | **[crates.io]** | `cargo install zoxide` | +| *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 | [AUR] | `yay -Sy zoxide-bin` | +| CentOS 7+ | [Copr] | `dnf copr enable atim/zoxide`
`dnf install zoxide` | +| Debian Testing | [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` | +| NixOS | [nixpkgs] | `nix-env -iA nixpkgs.zoxide` | +| Parrot OS | | `apt install zoxide` | +| Ubuntu 21.04+ | [Ubuntu Packages] | `apt install zoxide` | +| Void Linux | [Void Linux Packages] | `xbps-install -S zoxide` | + +
+ +
+macOS + +To install `zoxide`, run this command in your terminal: ```sh -curl.exe -A "MS" https://webinstall.dev/zoxide | powershell +curl -sS https://webinstall.dev/zoxide | bash ``` -Alternatively, you can install it using a package manager: - -On **Linux**: - -| Distribution | Repository | Instructions | -| ------------------ | ----------------------- | ------------------------------------------------------------------------------------------------------ | -| ***Any*** | **[crates.io]** | `cargo install zoxide` | -| *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 | [AUR] | `yay -Sy zoxide-bin` | -| CentOS 7+ | [Copr] | `dnf copr enable atim/zoxide`
`dnf install zoxide` | -| Debian Testing | [Debian Packages] | `apt install zoxide` | -| Devuan 4.0+ | [Devuan Packages] | `apt install zoxide` | -| Fedora 32+ | [Fedora Packages] | `dnf install zoxide` | -| Gentoo | [dm9pZCAq Overlay] | `eselect repository enable dm9pZCAq`
`emerge --sync dm9pZCAq`
`emerge app-shells/zoxide` | -| NixOS | [nixpkgs] | `nix-env -iA nixpkgs.zoxide` | -| Parrot OS | | `apt install zoxide` | -| Ubuntu 21.04+ | [Ubuntu Packages] | `apt install zoxide` | -| Void Linux | [Void Linux Packages] | `xbps-install -S zoxide` | - -On **macOS**: +Alternatively, you can use a package manager: | Repository | Instructions | | --------------- | ------------------------------------- | @@ -73,7 +84,18 @@ On **macOS**: | [Homebrew] | `brew install zoxide` | | [MacPorts] | `port install zoxide` | -On **Windows**: +
+ +
+Windows + +To install `zoxide`, run this command in your command prompt: + +```sh +curl.exe -A "MS" https://webinstall.dev/zoxide | powershell +``` + +Alternatively, you can use a package manager: | Repository | Instructions | | --------------- | ------------------------------------- | @@ -82,7 +104,12 @@ On **Windows**: | [conda-forge] | `conda install -c conda-forge zoxide` | | [Scoop] | `scoop install zoxide` | -On **BSD**: +
+ +
+BSD + +To install `zoxide`, use a package manager: | Distribution | Repository | Instructions | | ------------- | --------------- | ---------------------- | @@ -91,33 +118,51 @@ On **BSD**: | FreeBSD | [FreshPorts] | `pkg install zoxide` | | NetBSD | [pkgsrc] | `pkgin install zoxide` | -On **Android**: +
+ +
+Android + +To install `zoxide`, use a package manager: | Repository | Instructions | | ---------- | -------------------- | | [Termux] | `pkg install zoxide` | +
+ ### Step 2: Install `fzf` (optional) -[`fzf`][fzf] is a command-line fuzzy finder, used by zoxide for interactive -selection. Installation instructions can be found [here][fzf-installation]. +[`fzf`][fzf] is a command-line fuzzy finder, used by `zoxide` for interactive +selection ([installation instructions][fzf-installation]). ### Step 3: Add `zoxide` to your shell -If you currently use `z`, `z.lua`, or `zsh-z`, you may want to first import -your existing entries into `zoxide`: +If you currently use any of the following utilities, you may want to import +your data into `zoxide`: + +
+autojump ```sh -zoxide import --from z path/to/db +zoxide import --from autojump path/to/db ``` -Alternatively, for `autojump` (note that scores are not imported): +
+ +
+z, z.lua, or zsh-z ```sh -zoxide import --from autojump path/to/db +zoxide import --from z path/to/db ``` -#### `bash` +
+ +Now, initialize `zoxide` on your shell: + +
+bash Add this to your configuration (usually `~/.bashrc`): @@ -125,7 +170,10 @@ Add this to your configuration (usually `~/.bashrc`): eval "$(zoxide init bash)" ``` -#### `elvish` +
+ +
+elvish Add this to your configuration (usually `~/.elvish/rc.elv`): @@ -133,7 +181,10 @@ Add this to your configuration (usually `~/.elvish/rc.elv`): eval (zoxide init elvish | slurp) ``` -#### `fish` +
+ +
+fish Add this to your configuration (usually `~/.config/fish/config.fish`): @@ -141,9 +192,12 @@ Add this to your configuration (usually `~/.config/fish/config.fish`): zoxide init fish | source ``` -#### `nushell 0.32.0+` +
+ +
+nushell 0.32+ -Initialize zoxide's Nushell script: +Initialize the `zoxide` script: ```sh zoxide init nushell --hook prompt | save ~/.zoxide.nu @@ -158,7 +212,10 @@ startup = ["zoxide init nushell --hook prompt | save ~/.zoxide.nu", "source ~/.z You can replace `__zoxide_prompt` with a custom prompt. -#### `powershell` +
+ +
+powershell Add this to your configuration (the location is stored in `$profile`): @@ -169,7 +226,10 @@ Invoke-Expression (& { }) ``` -#### `xonsh` +
+ +
+xonsh Add this to your configuration (usually `~/.xonshrc`): @@ -177,7 +237,10 @@ Add this to your configuration (usually `~/.xonshrc`): execx($(zoxide init xonsh), 'exec', __xonsh__.ctx, filename='zoxide') ``` -#### `zsh` +
+ +
+zsh Add this to your configuration (usually `~/.zshrc`): @@ -185,7 +248,10 @@ Add this to your configuration (usually `~/.zshrc`): eval "$(zoxide init zsh)" ``` -#### Any POSIX shell +
+ +
+Any POSIX shell Add this to your configuration: @@ -193,27 +259,35 @@ Add this to your configuration: eval "$(zoxide init posix --hook prompt)" ``` +
+ ## Configuration -### `init` flags +### Flags + +When calling `zoxide init`, the following flags are available: -- `--cmd`: changes the prefix of predefined aliases (`z`, `zi`). +- `--cmd` + - Changes the prefix of predefined aliases (`z`, `zi`). - e.g. `--cmd j` would change the aliases to `j` and `ji` respectively. -- `--hook `: change how often zoxide increments a directory's score: - - `none`: never automatically add directories to zoxide. - - `prompt`: add the current directory to zoxide at every shell prompt. - - `pwd`: whenever the user changes directories, add the new directory to - zoxide. -- `--no-aliases`: don't define extra aliases (`z`, `zi`). +- `--hook ` + - Changes how often `zoxide` increments a directory's score: + | Hook | Description | + | -------- | --------------------------------- | + | `none` | Never | + | `prompt` | At every shell prompt | + | `pwd` | Whenever the directory is changed | +- `--no-aliases` + - Don't define extra aliases (`z`, `zi`). - These functions will still be available in your shell as `__zoxide_z` and - `__zoxide_zi`, should you choose to use them elsewhere. + `__zoxide_zi`, should you choose to redefine them. ### Environment variables Be sure to set these before calling `zoxide init`. - `_ZO_DATA_DIR` - - Specifies the directory in which zoxide should store its database. + - Specifies the directory in which `zoxide` should store its database. - The default value varies across OSes: | OS | Path | Example | | ----------- | ---------------------------------------- | ------------------------------------------ | @@ -269,14 +343,15 @@ Be sure to set these before calling `zoxide init`. [crates.io]: https://crates.io/crates/zoxide [debian packages]: https://packages.debian.org/testing/admin/zoxide [devuan packages]: https://pkginfo.devuan.org/cgi-bin/package-query.html?c=package&q=zoxide -[dm9pzcaq overlay]: https://github.com/gentoo-mirror/dm9pZCAq [dports]: https://github.com/DragonFlyBSD/DPorts/tree/master/sysutils/zoxide [fedora packages]: https://src.fedoraproject.org/rpms/rust-zoxide [freshports]: https://www.freshports.org/sysutils/zoxide/ [fzf-installation]: https://github.com/junegunn/fzf#installation [fzf]: https://github.com/junegunn/fzf [glob]: https://man7.org/linux/man-pages/man7/glob.7.html +[guru overlay]: https://github.com/gentoo-mirror/guru [homebrew]: https://formulae.brew.sh/formula/zoxide +[issues]: https://github.com/ajeetdsouza/zoxide/issues/new [linuxbrew]: https://formulae.brew.sh/formula-linux/zoxide [macports]: https://ports.macports.org/port/zoxide/summary [neovim]: https://github.com/neovim/neovim