diff options
Diffstat (limited to 'plugins/wd/README.md')
| -rw-r--r-- | plugins/wd/README.md | 247 |
1 files changed, 174 insertions, 73 deletions
diff --git a/plugins/wd/README.md b/plugins/wd/README.md index b1deeffd5..8791f9f0e 100644 --- a/plugins/wd/README.md +++ b/plugins/wd/README.md @@ -1,158 +1,259 @@ -wd -== +# wd [](https://travis-ci.org/mfaerevaag/wd) -`wd` (*warp directory*) lets you jump to custom directories in zsh, without using `cd`. Why? Because `cd` seems inefficient when the folder is frequently visited or has a long path. +`wd` (*warp directory*) lets you jump to custom directories in zsh, without using `cd`. +Why? +Because `cd` seems inefficient when the folder is frequently visited or has a long path.  -*NEWS*: If you are not using zsh, check out the c-port, [wd-c](https://github.com/mfaerevaag/wd-c), which works with all shells using wrapper functions. +## Setup -### Setup +### [oh-my-zsh](https://github.com/ohmyzsh/ohmyzsh) -### oh-my-zsh +`wd` comes bundled with oh-my-zsh! -`wd` comes bundled with [oh-my-zshell](https://github.com/robbyrussell/oh-my-zsh)! +Just add the plugin in your `.zshrc` file: -Just add the plugin in your `~/.zshrc` file: +```zsh +plugins=(... wd) +``` - plugins=(... wd) +### [Antigen](https://github.com/zsh-users/antigen) +In your `.zshrc`: -#### Automatic +```zsh +antigen bundle mfaerevaag/wd +``` -Run either in terminal: +### [Antibody](https://github.com/getantibody/antibody) - * `curl -L https://github.com/mfaerevaag/wd/raw/master/install.sh | sh` +In your `.zshrc`: - * `wget --no-check-certificate https://github.com/mfaerevaag/wd/raw/master/install.sh -O - | sh` +```zsh +antibody bundle mfaerevaag/wd +``` -##### Arch ([AUR](https://aur.archlinux.org/)) +### Arch ([AUR](https://aur.archlinux.org/packages/zsh-plugin-wd-git/)) - # yaourt -S zsh-plugin-wd-git +1. Install from the AUR +```zsh +yay -S zsh-plugin-wd-git +# or use any other AUR helper +``` -#### Manual +2. Then add to your `.zshrc`: - * Clone this repo to your liking +```zsh +wd() { + . /usr/share/wd/wd.sh +} +``` - * Add `wd` function to `.zshrc` (or `.profile` etc.): +### [zplug](https://github.com/zplug/zplug) - wd() { - . ~/path/to/cloned/repo/wd/wd.sh - } +```zsh +zplug "mfaerevaag/wd", as:command, use:"wd.sh", hook-load:"wd() { . $ZPLUG_REPOS/mfaerevaag/wd/wd.sh }" +``` - * Install manpage. From `wd`'s base directory (requires root permissions): +### Automatic - # cp wd.1 /usr/share/man/man1/wd.1 - # chmod 644 /usr/share/man/man1/wd.1 +_Note: automatic install does not provide the manpage. It is also poor security practice to run remote code without first reviewing it, so you ought to look [here](https://github.com/mfaerevaag/wd/blob/master/install.sh)_ - Note, when pulling and updating `wd`, you'll need to do this again in case of changes to the manpage. +Run either command in your terminal: +```zsh +curl -L https://github.com/mfaerevaag/wd/raw/master/install.sh | sh +``` -#### Completion +or -If you're NOT using [oh-my-zsh](https://github.com/robbyrussell/oh-my-zsh) and you want to utilize the zsh-completion feature, you will also need to add the path to your `wd` installation (`~/bin/wd` if you used the automatic installer) to your `fpath`. E.g. in your `~/.zshrc`: +```zsh +wget --no-check-certificate https://github.com/mfaerevaag/wd/raw/master/install.sh -O - | sh +``` - fpath=(~/path/to/wd $fpath) +### Manual + +1. Clone this repository on your local machine in a sensible location (if you know what you're doing of course all of this is up to you): + +```zsh +git clone git@github.com:mfaerevaag/wd.git ~/.local/wd --depth 1 +``` + +2. Add `wd` function to `.zshrc` (or `.profile` etc.): + +```zsh +wd() { + . ~/.local/wd/wd.sh +} +``` + +3. Install manpage (optional): + +```zsh +sudo cp ~/.local/wd/wd.1 /usr/share/man/man1/wd.1 +sudo chmod 644 /usr/share/man/man1/wd.1 +``` + +**Note:** when pulling and updating `wd`, you'll need to repeat step 3 should the manpage change + +## Completion + +If you're NOT using [oh-my-zsh](https://github.com/robbyrussell/oh-my-zsh) and you want to utilize the zsh-completion feature, you will also need to add the path to your `wd` installation (`~/bin/wd` if you used the automatic installer) to your `fpath`. +E.g. in your `~/.zshrc`: + +```zsh +fpath=(~/path/to/wd $fpath) +``` Also, you may have to force a rebuild of `zcompdump` by running: - $ rm -f ~/.zcompdump; compinit +```zsh +rm -f ~/.zcompdump; compinit +``` + +## Usage + +* Add warp point to current working directory: + +```zsh +wd add foo +``` + +If a warp point with the same name exists, use `wd add foo --force` to overwrite it. +**Note:** a warp point cannot contain colons, or consist of only spaces and dots. +The first will conflict in how `wd` stores the warp points, and the second will conflict with other features, as below. +You can omit point name to automatically use the current directory's name instead. -### Usage +* From any directory, warp to `foo` with: - * Add warp point to current working directory: +```zsh +wd foo +``` - $ wd add foo +* You can also warp to a directory within `foo`, with autocompletion: - If a warp point with the same name exists, use `add!` to overwrite it. +```zsh +wd foo some/inner/path +``` - Note, a warp point cannot contain colons, or only consist of only spaces and dots. The first will conflict in how `wd` stores the warp points, and the second will conflict with other features, as below. +* You can warp back to previous directory and higher, with this dot syntax: - You can omit point name to use the current directory's name instead. +```zsh +wd .. +wd ... +``` - * From an other directory (not necessarily), warp to `foo` with: +This is a wrapper for the zsh's `dirs` function. +_You might need to add `setopt AUTO_PUSHD` to your `.zshrc` if you are not using [oh-my-zsh](https://github.com/ohmyzsh/ohmyzsh)._ - $ wd foo +* Remove warp point: - * You can warp back to previous directory, and so on, with this dot syntax: +```zsh +wd rm foo +``` - $ wd .. - $ wd ... +You can omit point name to use the current directory's name instead. - This is a wrapper for the zsh `dirs` function. - (You might need `setopt AUTO_PUSHD` in your `.zshrc` if you hare not using [oh-my-zshell](https://github.com/robbyrussell/oh-my-zsh)). +* List all warp points (stored in `~/.warprc` by default): - * Remove warp point test point: +```zsh +wd list +``` - $ wd rm foo +* List files in given warp point: - You can omit point name to use the current directory's name instead. +```zsh +wd ls foo +``` - * List all warp points (stored in `~/.warprc`): +* Show path of given warp point: - $ wd list +```zsh +wd path foo +``` - * List files in given warp point: +* List warp points to current directory, or optionally, path to given warp point: - $ wd ls foo +```zsh +wd show +``` - * Show path of given warp point: +* Remove warp points to non-existent directories. - $ wd path foo +```zsh +wd clean +``` - * List warp points to current directory, or optionally, path to given warp point: +Use `wd clean --force` to not be prompted with confirmation. - $ wd show +* Print usage info: - * Remove warp points to non-existent directories. +```zsh +wd help +``` - $ wd clean +The usage will be printed also if you call `wd` with no command - Use `clean!` to not be prompted with confirmation (force). +* Print the running version of `wd`: - * Print usage with no opts or the `help` argument: +```zsh +wd --version +``` - $ wd help +* Specifically set the config file (default being `~/.warprc`), which is useful for testing: - * Print the running version of `wd`: +```zsh +wd --config ./file <command> +``` - $ wd --version +* Force `exit` with return code after running. This is not default, as it will *exit your terminal*, though required for testing/debugging. - * Specifically set the config file (default `~/.warprc`), which is useful when testing: +```zsh +wd --debug <command> +``` - $ wd --config ./file <action> +* Silence all output: - * Force `exit` with return code after running. This is not default, as it will *exit your terminal*, though required when testing/debugging. +```zsh +wd --quiet <command> +``` - $ wd --debug <action> +## Configuration - * Silence all output: +You can configure `wd` with the following environment variables: - $ wd --quiet <action> +### `WD_CONFIG` +Defines the path where warp points get stored. Defaults to `$HOME/.warprc`. -### Testing +## Testing -`wd` comes with a small test suite, run with [shunit2](https://code.google.com/p/shunit2/). This can be used to confirm that things are working as it should on your setup, or to demonstrate an issue. +`wd` comes with a small test suite, run with [shunit2](https://github.com/kward/shunit2). This can be used to confirm that things are working as they should on your setup, or to demonstrate an issue. To run, simply `cd` into the `test` directory and run the `tests.sh`. - $ ./tests.sh +```zsh +cd ./test +./tests.sh +``` +## Maintainers -### License +Following @mfaerevaag stepping away from active maintainership of this repository, the following users now are also maintainers of the repo: -The project is licensed under the [MIT-license](https://github.com/mfaerevaag/wd/blob/master/LICENSE). +* @alpha-tango-kilo +* @MattLewin -### Finally +Anyone else contributing is greatly appreciated and will be mentioned in the release notes! -If you have issues, feedback or improvements, don't hesitate to report it or submit a pull-request. In the case of an issue, we would much appreciate if you would include a failing test in `test/tests.sh`. For an explanation on how to run the tests, read the section "Testing" in this README. +--- Credit to [altschuler](https://github.com/altschuler) for an awesome idea. |