worm_hole 4.1.0

# Worm Hole
## Table of Contents
- [Introduction](#introduction)
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage](#usage)
- [License](#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](https://github.com/ajeetdsouza/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](https://www.rust-lang.org/tools/install) installed, you can install worm hole with cargo.
```shell
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](https://www.rust-lang.org/tools/install) 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
```shell
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, you can then eval the output in your shell's configuration file.
```shell
eval "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    |

For nushell user you can't use the `eval` command therefore you need to write the output to a file and load it as a module in nushell:
```nu
worm_hole init nu out> ~/.config/nushell/worm_hole.nu
```
Then you can source the file in your nushell configuration file:
```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 <alias> | Changes the command used to call worm_hole                  |
| --cd        <alias> | Changes the command used to change directory                |
| --add       <alias> | Adds a command to add a new alias-path pairs                |
| --remove    <alias> | Adds a command to remove an alias-path pair                 |
| --list      <alias> | Adds a command to list all alias-path pairs                 |
| --search    <alias> | Adds a command to search for an alias from its path         |
| --query     <alias> | Adds a command to query a path from an alias                |
| --edit      <alias> | Adds a command to edit the path of an alias-path pair       |
| --rename    <alias> | 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:
```shell
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):
```shell
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`
```nushell
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
```shell
> wh add foo /path/to/foo
> wh add bar # if no path is given, the current directory is used
```

### Move to a directory
```shell
> 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
```shell
> wh query foo
/path/to/foo
> wh list
foo -> /path/to/foo
bar -> /some/directory
> 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
```

### Edit an alias-path pair
```shell
> wh list
foo -> /path/to/foo
bar -> /some/directory
> wh edit foo /path/to/bar
> wh list
foo -> /path/to/bar
bar -> /some/directory
> cs /path/to/foobar
> wh edit foo # if no path is given, the current directory is used
> wh list
foobar -> /path/to/foobar
bar    -> /some/directory
> wh rename foo foobar
> wh list
foobar -> /path/to/foobar
bar    -> /some/directory
```

### Remove an alias-path pair
```shell
> wh list
foobar -> /path/to/foobar
bar    -> /some/directory
> wh remove bar
> wh list
bar -> /some/directory
```

## License
This project is licensed under the [GPL-3.0-or-later](https://www.gnu.org/licenses/gpl-3.0.en.html) license.

### TL;DR
This is a human-readable summary of [the license](COPYING), 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     |                              |             |