stow/oh-my-zsh/.oh-my-zsh/plugins/wd/README.md

   1 # wd
   2
   3 [![Build Status](https://travis-ci.org/mfaerevaag/wd.png?branch=master)](https://travis-ci.org/mfaerevaag/wd)
   4
   5 `wd` (*warp directory*) lets you jump to custom directories in zsh, without using `cd`.
   6 Why?
   7 Because `cd` seems inefficient when the folder is frequently visited or has a long path.
   8
   9 ![tty.gif](https://raw.githubusercontent.com/mfaerevaag/wd/master/tty.gif)
  10
  11 ## Setup
  12
  13 ### [oh-my-zsh](https://github.com/ohmyzsh/ohmyzsh)
  14
  15 `wd` comes bundled with oh-my-zsh!
  16
  17 Just add the plugin in your `.zshrc` file:
  18
  19 ```zsh
  20 plugins=(... wd)
  21 ```
  22
  23 ### [Antigen](https://github.com/zsh-users/antigen)
  24
  25 In your `.zshrc`:
  26
  27 ```zsh
  28 antigen bundle mfaerevaag/wd
  29 ```
  30
  31 ### [Antibody](https://github.com/getantibody/antibody)
  32
  33 In your `.zshrc`:
  34
  35 ```zsh
  36 antibody bundle mfaerevaag/wd
  37 ```
  38
  39 ### Arch ([AUR](https://aur.archlinux.org/packages/zsh-plugin-wd-git/))
  40
  41 1. Install from the AUR
  42
  43 ```zsh
  44 yay -S zsh-plugin-wd-git
  45 # or use any other AUR helper
  46 ```
  47
  48 2. Then add to your `.zshrc`:
  49
  50 ```zsh
  51 wd() {
  52     . /usr/share/wd/wd.sh
  53 }
  54 ```
  55
  56 ### [zplug](https://github.com/zplug/zplug)
  57
  58 ```zsh
  59 zplug "mfaerevaag/wd", as:command, use:"wd.sh", hook-load:"wd() { . $ZPLUG_REPOS/mfaerevaag/wd/wd.sh }"
  60 ```
  61
  62 ### Automatic
  63
  64 _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)_
  65
  66 Run either command in your terminal:
  67
  68 ```zsh
  69 curl -L https://github.com/mfaerevaag/wd/raw/master/install.sh | sh
  70 ```
  71
  72 or
  73
  74 ```zsh
  75 wget --no-check-certificate https://github.com/mfaerevaag/wd/raw/master/install.sh -O - | sh
  76 ```
  77
  78 ### Manual
  79
  80 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):
  81
  82 ```zsh
  83 git clone git@github.com:mfaerevaag/wd.git ~/.local/wd --depth 1
  84 ```
  85
  86 2. Add `wd` function to `.zshrc` (or `.profile` etc.):
  87
  88 ```zsh
  89 wd() {
  90     . ~/.local/wd/wd.sh
  91 }
  92 ```
  93
  94 3. Install manpage (optional):
  95
  96 ```zsh
  97 sudo cp ~/.local/wd/wd.1 /usr/share/man/man1/wd.1
  98 sudo chmod 644 /usr/share/man/man1/wd.1
  99 ```
 100
 101 **Note:** when pulling and updating `wd`, you'll need to repeat step 3 should the manpage change
 102
 103 ## Completion
 104
 105 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`.
 106 E.g. in your `~/.zshrc`:
 107
 108 ```zsh
 109 fpath=(~/path/to/wd $fpath)
 110 ```
 111
 112 Also, you may have to force a rebuild of `zcompdump` by running:
 113
 114 ```zsh
 115 rm -f ~/.zcompdump; compinit
 116 ```
 117
 118 ## Usage
 119
 120 * Add warp point to current working directory:
 121
 122 ```zsh
 123 wd add foo
 124 ```
 125
 126 If a warp point with the same name exists, use `wd add foo --force` to overwrite it.
 127
 128 **Note:** a warp point cannot contain colons, or consist of only spaces and dots.
 129 The first will conflict in how `wd` stores the warp points, and the second will conflict with other features, as below.
 130
 131 You can omit point name to automatically use the current directory's name instead.
 132
 133 * From any directory, warp to `foo` with:
 134
 135 ```zsh
 136 wd foo
 137 ```
 138
 139 * You can also warp to a directory within `foo`, with autocompletion:
 140
 141 ```zsh
 142 wd foo some/inner/path
 143 ```
 144
 145 * You can warp back to previous directory and higher, with this dot syntax:
 146
 147 ```zsh
 148 wd ..
 149 wd ...
 150 ```
 151
 152 This is a wrapper for the zsh's `dirs` function.
 153 _You might need to add `setopt AUTO_PUSHD` to your `.zshrc` if you are not using [oh-my-zsh](https://github.com/ohmyzsh/ohmyzsh)._
 154
 155 * Remove warp point:
 156
 157 ```zsh
 158 wd rm foo
 159 ```
 160
 161 You can omit point name to use the current directory's name instead.
 162
 163 * List all warp points (stored in `~/.warprc` by default):
 164
 165 ```zsh
 166 wd list
 167 ```
 168
 169 * List files in given warp point:
 170
 171 ```zsh
 172 wd ls foo
 173 ```
 174
 175 * Show path of given warp point:
 176
 177 ```zsh
 178 wd path foo
 179 ```
 180
 181 * List warp points to current directory, or optionally, path to given warp point:
 182
 183 ```zsh
 184 wd show
 185 ```
 186
 187 * Remove warp points to non-existent directories.
 188
 189 ```zsh
 190 wd clean
 191 ```
 192
 193 Use `wd clean --force` to not be prompted with confirmation.
 194
 195 * Print usage info:
 196
 197 ```zsh
 198 wd help
 199 ```
 200
 201 The usage will be printed also if you call `wd` with no command
 202
 203 * Print the running version of `wd`:
 204
 205 ```zsh
 206 wd --version
 207 ```
 208
 209 * Specifically set the config file (default being `~/.warprc`), which is useful for testing:
 210
 211 ```zsh
 212 wd --config ./file <command>
 213 ```
 214
 215 * Force `exit` with return code after running. This is not default, as it will *exit your terminal*, though required for testing/debugging.
 216
 217 ```zsh
 218 wd --debug <command>
 219 ```
 220
 221 * Silence all output:
 222
 223 ```zsh
 224 wd --quiet <command>
 225 ```
 226
 227 ## Configuration
 228
 229 You can configure `wd` with the following environment variables:
 230
 231 ### `WD_CONFIG`
 232
 233 Defines the path where warp points get stored. Defaults to `$HOME/.warprc`.
 234
 235 ## Testing
 236
 237 `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.
 238
 239 To run, simply `cd` into the `test` directory and run the `tests.sh`.
 240
 241 ```zsh
 242 cd ./test
 243 ./tests.sh
 244 ```
 245
 246 ## Maintainers
 247
 248 Following @mfaerevaag stepping away from active maintainership of this repository, the following users now are also maintainers of the repo:
 249
 250 * @alpha-tango-kilo
 251
 252 * @MattLewin
 253
 254 Anyone else contributing is greatly appreciated and will be mentioned in the release notes!
 255
 256 ---
 257
 258 Credit to [altschuler](https://github.com/altschuler) for an awesome idea.
 259
 260 Hope you enjoy!