whi 0.3.1

Magically simple PATH management
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107

# whi

`whi` is a smarter `which` that also lets you rearrange your current shell’s `PATH` safely. Install the shell integration once, run the high level commands (`prefer`, `move`, `switch`, `clean`, `delete`, `diff`, `save`), and grab the helper shortcuts if you like terse aliases.

> **Heads up**: mutation commands only run after the integration exports `WHI_SHELL_INITIALIZED=1`. If you see the integration warning, run the snippet for your shell and add it to your config for persistence.

## Install & Integrate

```bash
cargo install whi
```

Pick the snippet for your shell and paste it into a terminal. Add the same line to your shell config so it runs on startup.

```bash
# Bash
eval "$(whi init bash)"      # add to ~/.bashrc (or the file you source)

# Zsh
eval "$(whi init zsh)"       # add to ~/.zshrc

# Fish
whi init fish | source        # add to ~/.config/fish/config.fish
```

The snippet defines helper functions and exports `WHI_SHELL_INITIALIZED=1` so the `whi` binary knows it is safe to mutate the live `PATH`.

## Core Commands

All of these operate on the current shell session. Each command prints the updated `PATH`; the integration captures the string and updates `PATH` for you.

```bash
# Prefer a specific executable or add a path
whi prefer cargo 5
whi prefer cargo ~/.cargo/bin
whi prefer cargo github release
whi prefer ~/.local/bin

# Move and swap entries by index (1-based)
whi move 12 1
whi switch 4 9

# Clean duplicates, delete entries
whi clean
whi delete 3 9
whi delete ~/.local/bin
whi delete build temp

# Inspect and persist PATH state
whi diff              # current shell
whi diff zsh          # another shell
whi diff full         # shorthand for --full
whi save              # current shell
whi save fish         # explicit
whi save all          # every shell
```

### Querying executables

```bash
whi node                 # show the first match (with PATH index)
whi --all node           # list every match
whi --full node          # list matches, then highlight PATH entries
whi --path "custom:path" python
```

Useful flags:
- `-a/--all`
- `-f/--full`
- `-l/--follow-symlinks`
- `-s/--stat`
- `-0/--print0`
- `-q/--quiet`
- `--silent`
- `--color <auto|never|always>`
- `--path <PATH>`

`whi --help` shows the verbs (`diff`, `save`, `prefer`, `move`, `switch`, `clean`, `delete`). The integration intercepts those public names and rewrites them to the hidden `__…` subcommands that actually mutate the environment.

## Helper Shortcuts

These are defined by the integration and map directly to the core commands:

```bash
whip cargo github release    # -> whi prefer ...
whim 12 1                    # -> whi move ...
whis 4 9                     # -> whi switch ...
whic                         # -> whi clean
whid 3 9                     # -> whi delete ...
whia python                  # -> whi --all python
```

Use whichever spelling you prefer—both routes converge in Rust.

## Persistence & Logs

- Saved PATH files live in `~/.whi/` (`saved_path_bash`, `saved_path_zsh`, `saved_path_fish`). `whi save all` refreshes all three. Each save creates a `*.bak` backup before overwriting.
- Session logs live in `${XDG_RUNTIME_DIR:-$TMPDIR}/whi-<uid>/session_<ppid>.log`. They track explicit moves/deletions so `whi diff` can distinguish explicit vs. implicit changes. When more than 30 logs accumulate, the oldest ones are pruned automatically.

## Notes

- Mutating commands exit with an instructional message if the integration is missing. Copy the snippet shown (or the table above), run it, and add it to your shell config for future sessions.
- If you want to script against `whi` directly, capture stdout and export the string yourself. The integration just automates that for interactive use.

## License

MIT