Worm Hole

Table of Contents

• Introduction
• Installation
• Configuration
• Usage
• License

Introduction

Worm hole is a faster way to navigate through your file system.
It is a command line tool that allows you to jump to your favorite directories by using a simple alias.

The idea of worm hole came to me while I was using zoxide which is a great tool for navigating through your file system.
The problem I faced with zoxide was that because it's trying to guess the directory you want to jump to based on which one you use the most often, it often jumped to the wrong directory.
I also saw that I was always using the same words to jump to the same directories so there was no reason to try to guess them.

Installation

With cargo

If you have Rust installed, you can install worm hole with cargo.

cargo install worm_hole --locked

Compiling from source

If you want to compile worm hole from source, you can do so by following these steps:

1. Ensure you have Rust installed.
2. Clone the repository
3. In the repository, compile the project
4. Copy the binary to a directory in your PATH
5. You can now remove the repository if you want

git clone --depth 1 --branch latest git@gitlab.com:Rignchen/worm_hole.git # https://gitlab.com/Rignchen/worm_hole.git
cd worm_hole
cargo build --release
cp target/release/worm_hole /usr/local/bin/
cd ..
rm -fr worm_hole # Remove the repository if you want

Configuration

Worm hole needs to be set up before you can use it.

Default setup

Worm hole has a command to generate the configuration it needs which can be added to your shell's configuration script

worm_hole init <shell> # Replace <shell> with the shell you are using (bash, zsh, fish)

This command sets up 2 aliases: | Command | Description | | wh | This command is used to call worm hole with it's database | | whcd | This command is used to move to the directory you want |

Bash

Simply add this to your ~/.bashrc

eval "$(worm_hole init bash)"

Zsh

Simply add this to your ~/.zshrc

eval "$(worm_hole init zsh)"

Fish

Simply add this to your ~/.config/fish/config.fish

worm_hole init fish | source

Nushell

For nushell the commands generate a module which you can store in a file

worm_hole init nu out> ~/.config/nushell/worm_hole.nu

Then you can add the following to your ~/.config/nushell/config.nu

use ~/.config/nushell/worm_hole.nu *

Custom setup

You can change the aliases to whatever you want by adding these flags to the command: | Flag | Description | | --worm-hole | Changes the command used to call worm_hole | | --cd | Changes the command used to change directory | | --add | Adds a command to add a new alias-path pairs | | --remove | Adds a command to remove an alias-path pair | | --list | Adds a command to list all alias-path pairs | | --search | Adds a command to search for an alias from its path | | --query | Adds a command to query a path from an alias | | --edit | Adds a command to edit the path of an alias-path pair | | --rename | Adds a command to rename an alias without changing the path |

You can also change the path to the database by adding the --db-path flag before the init keyword.

Example

For example if you add this to your shell's configuration file:

eval "worm_hole --db-path /path/to/db init bash --worm-hole wh2 --cd whcd2 --add wha --remove whrm --search whs --list whl --query whq --edit whe --rename whrn"

The sqlite database used by worm hole will be located at /path/to/db, then you will be able to use the following commands: | wh2 | call worm hole with it's database | | whcd2 | move to the directory you want (same as cd $(wh2 query foo)) | | wha | register a new alias-path pair | | whrm | forget an alias-path pair | | whs | search for aliases with path including the provided pattern | | whl | list all alias-path pairs | | whq | query a path from its alias | | whe | edit the path of an alias-path pair | | whrn | rename an alias without changing the path |

Multiple instances

Worm hole has not been created with the intention of having multiple instances connected to different databases, however it is still possible to do so (I do it on one of my machines).

To do so

• copy the setup command you used
• remove or change all your custom commands
• ensure that both instances are using different databases
• at least one of your instances should change the wh and whcd commands to avoid conflicts
• once this is done you need to change the name of a bash command __worm_hole_cd that is generated by the init command by piping the output into sed

Here's my setup with 2 instances of worm hole (I know I was not very creative with the names):

eval "$(worm_hole init zsh --add wha)"
eval "$(worm_hole --db-path $HOME/.wormhole2.db init zsh --worm-hole wh2 --cd whcd2 --add wha2 | sed -e 's/__worm_hole_cd/__worm_hole_cd2/g')"

Nushell

Since nushell keeps a module's non-exported functions from overlapping with other modules, you don't have to rename __worm_hole_cd

worm_hole init nu --add wha o> worm_hole.nu
worm_hole --db-path ($env.HOME | path join .wormhole2.db) init nu --worm-hole wh2 --cd whcd2 --add wha2 o> worm_hole2.nu
use worm_hole.nu *
use worm_hole2.nu *

Usage

Worm hole is very simple to use.
If you have a custom setup, you can use the commands you set up in the configuration file (if you changed wh or whcd these will have to be replaced by the new commands you set up).

Adding a new alias-path pair

> wh add foo /path/to/foo
> wh add bar # if no path is given, the current directory is used

Move to a directory

> pwd
/some/directory
> whcd foo
> pwd
/path/to/foo
> whcd # if no alias is given, go to home directory
> pwd
/home/user

Get an alias-path pair

> wh query foo
/path/to/foo
> wh ls # sorted alphabetically on the alias
bar -> /some/directory
foo -> /path/to/foo
> wh search f
foo -> /path/to/foo
> cd /path/to
> wh search # if no pattern is given search for paths inside the current directory
foo -> /path/to/foo

note: when you use the ls/search custom commands on nushell, the output gets parsed into table<alias: string, path: string>

> wh ls
╭───┬───────┬─────────────────╮
│ # │ alias │      path       │
├───┼───────┼─────────────────┤
│ 0 │ bar   │ /some/directory │
│ 1 │ foo   │ /path/to/foo    │
╰───┴───────┴─────────────────╯
> wh ls | to nuon
[[alias, path]; [bar, /some/directory], [foo, /path/to/foo]]

Edit an alias-path pair

> wh ls
bar -> /some/directory
foo -> /path/to/foo
> wh edit foo /path/to/bar
> wh ls
bar -> /some/directory
foo -> /path/to/bar
> cd /path/to/foobar
> wh edit foo # if no path is given, the current directory is used
> wh ls
bar -> /some/directory
foo -> /path/to/foobar
> wh rename foo foobar
> wh ls
bar    -> /some/directory
foobar -> /path/to/foobar

Remove an alias-path pair

> wh ls
foobar -> /path/to/foobar
bar    -> /some/directory
> wh rm bar
> wh ls
bar -> /some/directory

License

This project is licensed under the GPL-3.0-or-later license.

TL;DR

This is a human-readable summary of the license, it is not a legal document, do not rely on it for legal advice.

Permissions	Conditions	Limitations
Commercial use	Disclose source	Liability
Distribution	License and copyright notice	Warranty
Modification	Same license
Patent use	State changes
Private use