Warp Directory
This is a ruby implementation of the tool wd
(warp directory),
originally written as a ZSH
module
by Markus Færevaag.
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, 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:
~ ❯ 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:
/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):
/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
, orls
or any other command for that matter
Notable Differences with original wd
- instead of
wd add!
usewd add -f <point>
(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:
- This
wd
requires version 2+ of ruby interpreter. Check your default ruby withruby --version
. You should see something like "ruby 2.3.0p0....". If you see version 1.9 or earlier, upgrade your ruby withbrew update; brew install ruby
. - Install warp-dir gem:
bash ~ ❯ gem install warp-dir --no-ri --no-rdoc
- 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 (please use iTerm over Terminal — it's soooo much better!), and then type:
~ ❯ 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 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.
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.