kigster / warp-dir Goto Github PK

Warp Directory – a drop-in replacement (superset to be precise) of the nifty 'wd' ZSH module. This one is written in ruby, and works with any shell.

Home Page: https://github.com/kigster/warp-dir

License: MIT License

Ruby 93.00% Shell 7.00%

warp-dir's Introduction

Warp Directory

Table of Contents

1. Warp This
2. Installation
3. Usage
- 3.1. Command Completion in BASH
- 3.2. Config File (aka. Warp Points Database)
4. wd Concept
- 4.1. Notable Differences with original wd
- 4.2. Future Feature Brainstorm
  - 4.2.1. Simplify The CLI
5. Run Commands In A Warp Point
- 5.1. Networking
6. Development
7. Adding New Commands
8. Contributing
9. Author
10. License

Tip	You can read this README in a nicely formatted PDF Document.

This is a ruby implementation of the tool wd (warp directory), originally written as a ZSH module by Markus Færevaag.

I personally 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.

1. 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 yourself going into a small number of deeply nested folders with a long path prefix.

2. Installation

Three steps:

wd requires a Ruby interpreter version 2.2 higher.
- Please Check your default ruby with ruby --version. You should see something like "ruby 2.3.0p0….".
- If you see version 1.9 or earlier, please upgrade your ruby using the package manager native to your OS.
Install warp-dir ruby gem (note: you may need to prefix the command with sudo if you are installing into the "system" ruby namespace).
```
$ gem install warp-dir
```
The last step is to install the wd BASH function and auto-completion. This step appends the required shell function to your shell initialization file, that is specified with the warp-dir install --dotfile <shell-dot-file> command:
```
$ warp-dir install --dotfile ~/.bash_profile
Shell support is installed in the following files:
/Users/kig/.bash_profile
$ source ~/.bash_profile
# Now we can use 'wd' shortcut
$ wd --help
```

After the last step you need to restart your session, so — if you are on Mac OS X, — please reopen your Terminal or better yet — iTerm2, and then type:

$ wd help

If the above command returns a properly formatted help that looks like the image below, your setup is now complete!

3. 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/

3.1. Command Completion in BASH

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><TAB> you should see the list of all saved warp points as well as all of the local sub-directories relative to where you are at.

# And, it supports command completion in BASH!
$ wd<TAB><TAB>
# should print the list of registered warp points, and commands.

$ wd install --dotfile /Users/kig/.bash<TAB><TAB>
/Users/kig/.bash_login    /Users/kig/.bash_profile  /Users/kig/.bashrc

Command completion is activated by loading the ~/.bash_wd file that’s installed with warp-dir install command.

3.2. 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!

4. `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

4.1. Notable Differences with original `wd`

instead of wd add! use wd 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

4.2. Future Feature Brainstorm

4.2.1. Simplify The CLI

Questionable value, but this sort of interface appear a bit more consistent.

Still I am not sure I want to type wd -j proj or wd -a proj instead of wd proj and wd add proj…

  wd -j/--jump   point
  wd -a/--add    point
  wd -r/--remove point
  wd -l/--ls     point
  wd -p/--path   point

  wd -L/--list
  wd -C/--clean
  wd -S/--scan           # report whether points exist on the file system

5. Run Commands In A Warp Point

Pass an arbitrary command to execute, and return back to CWD.

  wd proj -x/--exec -- "command"

5.1. Networking

Can we go across SSH?

  wd add proj [email protected]:~/workspace/proj
  wd ls proj
  wd proj

This then establishes and SSH connection to the server and logs you into the shell. Should be pretty easy, I think :)

6. Development

Fork the repo to your github username, and create a feature branch. Run bundle install.

You can also run bin/console for an interactive prompt that will allow you to experiment.

To submit your change, create a new pull request, and ensure to provide tests for any new code.

7. Adding New Commands

Just follow the pattern in the lib/warp/dir/commands/ folder, copy and modify one of the existing commands. Command class name is used as an actual command.

Add a working rspec.

8. Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/kigster/warp-dir.

9. Author

10. License

This project is distributed under the MIT License.

warp-dir's People

Contributors

Stargazers

Watchers

Forkers

gitter-badger fossabot

warp-dir's Issues

wd into a folder that contains space is broken

❯ wd kindle
bash: cd: /Users/kig/Library/Containers/com.amazon.Kindle/Data/Library/Application: No such file or directory

load error during initialising command in linux/debian

hi,
i have popos (debian based).Installed warp-dir using gem install command.Please note as am installing in system wide had to use sudo prefix.
gem install warp-dir --no-doc
installation completed successful.
Based on instructions i ran the shell completion.
warp-dir install --dotfile ~/config/.config/.zshrc
received the below error message.

1: from /usr/local/bin/warp-dir:23:in `<main>'
/usr/local/bin/warp-dir:23:in `load': cannot load such file -- /var/lib/gems/2.7.0/gems/warp-dir-1.6.2/exe/warp-dir (LoadError)

Please let me know if you require more details.
thanks

Warp-dir breaks when running from a folder with an existing Gemfile

The usage of the gem assumes that you will be bookmarking the current directory, by running warp-dir add name (where name becomes the shortcut you use later to go back to this folder).

The gem works perfectly fine for any folder, except when the current folder is a project with a Gemfile in it. In that case, the gem gets confused, and from what it looks like, uses the local Gemfile to load its dependencies, which obviously fails. The following terminal session illustrates this problem:

Source code of warp-dir does not even have any runtime dependencies on the Bundler. The source of the gem does not even have Gemfile, unless I run a special rake task, meant to be run only in development (rake development:bundler:install) which generates a temporary Gemfile and then uses it to install dependencies:

Add emacs support for warp-dir

Hey friends,
this is not an issue, but rather the start of a feature others may want to use, or may find helpful.

Motivation

Emacs has bookmarks, which serve the same purpose as warp-dir. However, I wanted a way to sync the two.

Implementation

I wrote a small Emacs package which will read from ~/.warprc, ask the user to pick a destination, and warp to that destination.

(defun my-file-contents (filename)
  "Return the contents of FILENAME."
  (with-temp-buffer
    (insert-file-contents filename)
    (buffer-string)))

(defun get-wd-list ()
  " get .warprc as list"
  (split-string (my-file-contents "~/.warprc")))

(defun warp-dir ()
  "Prompt user in mini buffer to select warp destination."
  (interactive)
  (let
    ((kv (completing-read
	 "Warp Directory: "
	 (get-wd-list)
	 nil t)))
    (dired (cdr (split-string kv ":")))))

(provide 'warp-dir)

Example Usage

Missing Features

creating, updating, and deleting warp spots from within Emacs.
I could tidy up the presentation of the spot selector to just show keys.

What to do with all of this?

I just wanted to get this somewhere on the web so that, if someone uses Emacs and wants this functionality, they have a place they can start.

Feel free to immediately close the issue, or, if you use Emacs, point me in a direction that you think is appropriate for sharing.

Thanks.

[feature] WarpDir interface 2.0

Warp-Dir 2.0

Definitions

warp directory is the actual directory / folder on the filesystem that we want to bookmark.
warp point is the name of the "bookmark" leading to the actual directory on the file system.
warp-dir is the ruby gem that provides most of the functionality
wd is the bash shell wraper that provides streamlined interface to warp-dir and is assumed to be the primary interface for the gem.

Current Interface 1.0

Right now you do:

wd add <point>
wd ls 
wd <point>
wd remove <point>

Which means that commands and warp point names may clash. Eg, you can never have a warp point named ls or add. It also means that adding commands and extending warp-dir only makes the name collisions worse.

I would like to make the interface more consistent and easier to work with. In particular it should:

be easy to remember
be easy to extend
not clash by name with directories
be smarter about bash completion
have a mode where it works just like cd and can be used as a general cd replacement
easier to install and update (automatically updates shell extension with each new gem version)

Proposed Interface 2.0

wd <point expression> [--command [ args ...]]

Warp Point Expressions

In order to quickly select one or more warp points, the following syntax is proposed:

@point denotes a single warp point by name
Regular Expressions matching by Warp Point Name:
- [+]@/regex/ denotes an egrep regular expression matching zero or more warp points to be included (plus sign is optional).
- -@/regex/ means exclude matching
Tags
- -t tag1,tag2 �� or +#tag can be used to select warp points matching one of a given set of tags
- -T tag3,tag4 or -#tag can be used to exclude warp points matching the tags.

Boolean Logic is as follows:

if both include and exclude patterns are provided, then the include ones are ran first, and exclude pattern are then applied to and subtracted from the include results.
- if only exclude is provided, include set is assumed to be the full set of warp points.

Below we'll use @point to refer to each point by its exact name, and <@point expr> will denote the above expression.

Using slashes, we can supply a regular expression that can be passed to egrep, the more advanced grep with full regular expression syntax. We will also use the same syntax when we call find within the warp directories, making find fully regular expression aware (see this discussion).

Using tags we can aggregate some folders on the file system into logical groups, and then perform operations across them. For example, you might tag several folders with the same project name, and then run make across them all concurrently.

Adding Warp Points

To add a new directory as a warp point, you can use -a | --add command. However, there is a simpler way: trying to jump to a non-existent warp point is interpreted as adding current folder as a new warp point, and pops a question:

> wd fubar
Warp point fubar does not exist. 
Create (fubar ~> /Users/kig/projects/fubar)? [Y/n]

To avoid interactive check use either:

Explicit add command: wd < -a | --add > fubar [ folder ] (current folder is assumed, if none provided)
Or we can provide the third argument — a folder to warp to, or a "dot" for the current one:
```
wd @fubar .
wd @home /User/kig
```

The above syntax will silently create a warp point if none exist, or prompt for an action if it does.

Managing Warp Points

Tagging

Either of the three syntax forms are equivalent.

Note: it is likely that only the -t and -T syntax will be available initially.

wd @point [ -t tag1,tag2 -T tag3 ]         
wd @point +#tag1 +#tag2 -#tag3
wd @point --tags '+tag1 +tag2 -tag3'

Using +# or -t will add a tag to a point(s)

This can be done during add, or as a separate command:

wd @fubar . -t project-fubar  # add and tag
wd @fubar +#project-fubar     # tag existing point

Deleting

You can delete a single warp point, or multiple by using -d flag. Remember that you can preview your action by using -n flag or --dry-run.

wd  @point         < -d | --delete>
wd <@point expr>   < -d | --delete>

Undo

Warp dir maintains a full history of all commands that affect the warp-dir data store, and it can undo any number of them. Once again — __undo action only applies to commands that modify warp point directory, such as add/remove points, and tag points. To jump in the history see section below.

To undo a previous command:

wd --undo [ TAB ]         # show list of commands to undo
wd --undo [ -N  ]         # undo last N commands
wd --undo [  N  ]         # attempt to undo just one command, N back

WarpDir maintains a full history of all commands executed, together with a reverse command to undo each step. Therefore you can undo several steps back by passing a number with a dash, or a specific command several commands back using just the number. This will not always work, but an attempt is worth the effort.

Multi-step undo will rewind the history, and remove the last N commands while executing their reversals.

Discovering Warp Points and Jumping There

To list existing warp points run:

wdp                 [ @point expr ] 
wd [ -p | --print ] [ @point expr ]

Jumping between Warp Points

wd @point[/....]                # wd into warp directories

Since in the new interface warp points and their expressions always start with @, we can assume that a regular word as a second argument is a plain old directory. Therefore, wd can be used just like a 'cd' by passing a non-prefixed second argument. In fact, one of the design goals is to be able to alias cd to wd and have full cd functionality + wd functionality available.

wd directory[TAB]

History

WarpDir will maintain a full history of where the user jumped to and from.

wdh | wd --history               # display wd history
wd -                             # jump back one step
wd -4                            # jump back four steps

Running Commands

Perhaps the most experimental feature of wd is the ability to run ls, find and any other command across one or more warp points concurrently.

Since multiple warp points can belong to the same tag, you can quickly setup command that search for a filename across multiple disjointed directories, that are somehow part of the same project — perhaps these are microservices with their separate code-bases, etc.

# runs ls in the given warp points
wdl [@point expr ] [ /regex/ ] -- [ ls arguments ] 

# runs arbitrary command
wdx [@point expr ] [ /regex/ ] -- <command [ args ... ]> 

# runs find across warp points
wdf [@point expr ]  [ /regex/ ] -- <find arguments >

Output Filtering

You may have noticed that there is a second regular expression in the command line above, between the slashes. This can be optionally used to filte the output of all commands. It effectively works like piping to egrep of the entire output.

Examples

Find all folders that match 'src' in their name within all warp points that match 'workspace'.

wdf @//workspace/ /src/ -- -type d

Concurrency

Running commands concurrently produces output that can be confusing if it's not well understood.

By the default, warp-dir determines how many warp points match the provided expression and uses number of threads corresponding to it, up to 2 x (# of cpu cores). The output of multiple streams is interleaved line by line from each thread, so that individual lines should never be broken up.

You can control the concurrency factor of wd and limit number of threads it creates by passing -c CONCURRENCY flag. To switch to a serial mode, pass -c1 | --concurrency 1 flag. Passing 0 means default auto-concurrency mode. Numbers larger than the max value of 2 * (# of cpu cores) is ignored, and concurency is set to the max value.

Updated version of wd should be able to update it's shell wrapper

Right now updating warp-dir would not be able to cleanly replace the shell wrapper. This should be very simple to do, by moving wrapper into a ~/.bash_warpdir sourced in from the ~/.bashrc

Installation on Ubuntu in WSL2 fails to copy the .bash_wd file.

I have installed on Ubuntu on windows

sudo gem install warp-dir --no-document

and then installed warp-dir

sudo warp-dir install --dotfile ~/.profile

if I don't run this with sudo I get a load error.

Traceback (most recent call last):
        1: from /usr/local/bin/warp-dir:23:in `<main>'
/usr/local/bin/warp-dir:23:in `load': cannot load such file -- /var/lib/gems/2.7.0/gems/warp-dir-1.6.2/exe/warp-dir (LoadError)

Unfortunately when executed as sudo the installation doesn't correctly copy the .bash_wd file to the home directory.
Is there a workaround or solution?
Can I obtain the file, and just manually copy it in the meantime?

I have been hacking a bit, and it would seem to be a permission issue for the most part, /var/lib/gems/2.7.0/gems/warp-dir-1.6.2/exe/warp-dir can only be executed with sudo, and gem install (as an ordinary user) cannot access /var/lib/gems/...