# Warp Directory
[](https://badge.fury.io/rb/warp-dir)
[](https://travis-ci.org/kigster/warp-dir)
[](https://codeclimate.com/github/kigster/warp-dir)
[](https://codeclimate.com/github/kigster/warp-dir/coverage)
[](https://codeclimate.com/github/kigster/warp-dir)
[](https://gitter.im/kigster/warp-dir)
This is a ruby implementation of the tool `wd` (warp directory),
[originally written as a `ZSH` module](https://github.com/mfaerevaag/wd)
by [Markus Færevaag](https://github.com/mfaerevaag).
I personaly went back to `bash` after trying out `ZSH`, but it was the `wd` plugin that I really missed.
While Markus kindly offered a ruby version in a [separate branch of this module](https://github.com/mfaerevaag/wd/tree/ruby),
it wasn't quite as extensible as I wanted to (or well tested), so it ended up being an inspiration for this gem.
## Warp This
WarpDir is a UNIX command line tool that works somewhat similar to the standard built-in command `cd` — "change directory".
The main difference is that `wd` is able to add/remove/list folder "shortcuts", and allows you to jump to these shortcuts from anywhere on the filesystem.
This of this as a folder-navigation super-charge tool that you'd use on a most frequently-used set of folders. This becomes __really useful__ if you are often finding youself going into a small number of deeply nested folders with a long path prefix.
## Usage
__NOTE:__ in the below examples, the characters `~ ❯ ` denote the current shell prompt, showing the current folder you are in. The command to type is on the right hand side of the "❯".
Let's first bookmark a long directory:
```bash
~ ❯ cd ~/workspace/arduino/robots/command-bridge/src
~/workspace/arduino/robots/command-bridge/src ❯ wd add cbsrc
Warp point saved!
~/workspace/arduino/robots/command-bridge/src ❯ cd ~/workspace/c++/foo/src
~/workspace/c++/foo/src ❯ wd add foosrc
Warp point saved!
~/workspace/c++/foo/src ❯ cd /usr/local/Cellar
/usr/local/Cellar ❯ wd add brew
Warp point saved!
```
Now we can list/inspect current set of warp points:
```bash
/usr/local/Cellar ❯ wd l
cbsrc -> ~/workspace/arduino/robots/command-bridge/src
foosrc -> ~/workspace/c++/foo/src
brew -> /usr/local/Cellar
```
Now we can jump around these warp points, as well as run 'ls' inside (even passing arbitrary arguments to the `ls` itself):
```bash
/usr/local/Cellar ❯ wd cbsrc
~/workspace/arduino/robots/command-bridge/src ❯ wd foosrc
~/workspace/c++/foo/src ❯ 1 wd ls brew -- -alF | head -4 # run ls -alF inside /usr/local/Cellar
total 0
drwxrwx--- 73 kig staff 2482 May 7 15:29 ./
drwxrwx--- 21 kig staff 714 Apr 28 11:40 ../
drwxrwx--- 3 kig staff 102 Dec 24 03:14 ack/
```
### Command Completion
If you installed `wd` properly, it should register it's own command completion for BASH and be ready for your tabs :)
Note that you can use `wd` to change directory by giving an absolute or relative directory name, just like `cd` (so not just using warp-points), so when you type `wd [TAB]` you will see all saved warp points as well as the local directories you can `cd` into.
That's basically it!
### Config File (aka. Warp Points Database)
All of the mappings are stored in the `~/.warprc` file, where the warp point name is followed by a colon, and the path it maps to. So it's trivial to do a global search/replace on that file in your favorite editor, if, for example, a commond top level folder had changed.
The format of the file was left identical to that of the `ZSH` version of `wd` so that one could switch back and force between the two versions of `wd` and still be able to use their collection of warp points.
See? I think we thought of everything :)
Happy warping!
### Detailed Usage
## `wd` Concept
The overall concept comes from the realization that when we work on the command line, we often do things that `wd` tool provides straight out of the box, such as:
* we often have to deal with a limited number of folders at any given time
* on occastion have to jump between these folders (which we call __warp points__), which may require mult-level `cd` command, for example: `cd ~/workspace/foo/src/include/; ....; cd ~/Documents/Microsoft\ Word/; ...`
* seems like it should be easy to add, remove and list warp points
* everything should require typing few characters as possible :)
* it would be great to have full BASH completion support
Some future extensions could be based on some additional realizations:
* perhaps you might want to inspect a bookmarked folder without leaving your current place.
* maybe by inspecting we mean — running a `find`, or `ls` or any other command for that matter
### Notable Differences with original `wd`
* instead of `wd add!` use `wd add -f ` (or --force)
These features will be added shortly:
* for now `wd clean` is not supported
* for now history is not supported
* for now '-' is not supported
## Installation
Three steps:
1. This `wd` requires version 2+ of ruby interpreter. Check your default ruby with `ruby --version`. You should see something like "ruby 2.3.0p0....". If you see version 1.9 or earlier, upgrade your ruby with `brew update; brew install ruby`.
2. Install warp-dir gem:
```bash
~ ❯ gem install warp-dir --no-ri --no-rdoc
```
3. The last step is to install the `wd` BASH function and auto-completion:
```bash
~ ❯ warp-dir install --dotfile ~/.bash_profile
```
This last step appends the required shell function to the shell initialization file specified with the `--dotfile` flag. If you are unsure what that means, please run the command above as is.
And step 3 you will need to restart your shell, so reopen your Terminal or [iTerm2](https://www.iterm2.com/) (please use iTerm over Terminal — it's soooo much better!), and then type:
```bash
~ ❯ wd help
```
If the above command returns a properly formatted help like the image below, your setup
is now complete!
## Future Development
I have so many cool ideas about where this can go, that I created a
[dedicated page](ROADMAP.md) for the discussion of future features. Please head over
there if you'ld like to participate.
## Development
After checking out the repo, run `bin/setup` to install dependencies.
You can also run `bin/console` for an interactive prompt that will
allow you to experiment.
To install this gem onto your local machine, run `bundle exec rake install`.
To release a new version, update the version number in `version.rb`, and
then run `bundle exec rake release`, which will create a git tag for the
version, push git commits and tags, and push the `.gem` file
to [rubygems.org](https://rubygems.org).
## Adding New Commands
Just follow the patter in the `lib/warp/dir/commands/` folder, copy and modify
one of the existing commands. Command class name is used as an actual command.
## Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/kigster/warp-dir.
## Author
© 2016 Konstantin Gredeskoul, all rights reserved.
## License
This project is distributed under the [MIT License](https://raw.githubusercontent.com/kigster/warp-dir/master/LICENSE).