#hole #navigation #alias-path

bin+lib worm_hole

CLI tool to easily jump between directories

2 stable releases

1.1.1 Mar 21, 2025

#357 in Filesystem

Download history 226/week @ 2025-03-19

226 downloads per month

CC-BY-NC-SA-4.0

39KB
659 lines

Worm Hole

Table of Contents

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.

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 1.1.0 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, you can then eval the output in your shell's configuration file.

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

This command sets up 2 aliases:

  • 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

Custom setup

You can change the aliases to whatever you want by adding these flags to the command:

  • --worm-hole : Changes the command for the wh command
  • --cd : Changes the command for the whcd command
  • --add : Adds a command you can use to add a new pair alias/path to worm hole
  • --remove : Adds a command you can use to remove a pair alias/path from worm hole
  • --list : Adds a command you can use to list all the pairs alias/path in worm hole
  • --search : Adds a command you can use to search for an alias from it's path in worm hole
  • --query : Adds a command you can use to query a path from an alias in worm hole
  • --edit : Adds a command you can use to edit the path of an alias/path pair in worm hole
  • --rename : Adds a command you can use to rename an alias in worm hole 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 to call worm hole with it's database (for example wh2 add toto /path/to/toto)
  • whcd2 to move to the directory you want (same as cd $(wh2 query toto))
  • wha to add a new pair alias/path to worm hole
  • whrm to remove a pair alias/path from worm hole
  • whs to search for an alias from it's path in worm hole (for example whs /home/user will return all aliases from subdirectories of /home/user)
  • whl to list all the pairs alias/path in worm hole
  • whq to query a path from an alias in worm hole
  • whe to edit the path of an alias/path pair in worm hole
  • whrn to rename an alias in worm hole without changing the path

Multiple instances

Worm hole has not been created with the intention of having multiple instances connected to different databases on the same shell, 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')"

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 pair alias/path

wh add toto /path/to/toto
wh add tata # if no path is given, the current directory is used

Move to a directory

pwd # /home/user
whcd toto
pwd # /path/to/toto

Get an alias/path pair

wh query toto # /path/to/toto
wh list # toto -> /path/to/toto
wh search /path/to # toto -> /path/to/toto

Edit an alias/path pair

wh list # toto -> /path/to/toto
wh edit toto /path/to/tata
wh list # toto -> /path/to/tata
wh rename toto tata
wh list # tata -> /path/to/tata

Remove an alias/path pair

wh list # tata -> /path/to/tata
wh remove tata
wh list #

License

This project is licensed under the Creative Commons Attribution Non Commercial Share Alike 4.0 International 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.

You are free to:

  • Share — copy and redistribute my software in any medium or format
  • Adapt — remix, transform, and build upon my code

But you must follow these rules:

  • Attribution — You must give me appropriate credit, provide a link to the license and indicate the modifications you made to my code. You can do this in any way you like but not in a way that suggests I approve of your use of my code.
  • NonCommercial — You may not use my code for commercial purposes.
  • ShareAlike — You cannot change the license if you remix, transform, or build upon my code.
  • No additional restrictions — You can't restrict others from doing anything the license permits.

Dependencies

~1.5–2.1MB
~43K SLoC