@@ -0,0 +1,91 @@ |
| 1 | +# gump |
| 2 | + |
| 3 | +(noun) : directed momentum. |
| 4 | + |
| 5 | +## A smarter cd |
| 6 | + |
| 7 | +Directory jumper using frecency. Type directory fragments, land where you meant. |
| 8 | + |
| 9 | +``` |
| 10 | +projects # jumps to ~/code/projects |
| 11 | +gmp # jumps to ~/code/gump (fuzzy) |
| 12 | +doc my # jumps to ~/documents/myfiles (multi-term) |
| 13 | +``` |
| 14 | + |
| 15 | +No command prefix required. |
| 16 | + |
| 17 | +## Build |
| 18 | + |
| 19 | +```bash |
| 20 | +cargo build --release |
| 21 | +cp target/release/gump ~/.local/bin/ |
| 22 | +``` |
| 23 | + |
| 24 | +## Shell Setup |
| 25 | + |
| 26 | +Add to shell rc file: |
| 27 | + |
| 28 | +**Bash** (`~/.bashrc`) |
| 29 | +```bash |
| 30 | +eval "$(gump init bash)" |
| 31 | +``` |
| 32 | + |
| 33 | +**Zsh** (`~/.zshrc`) |
| 34 | +```zsh |
| 35 | +eval "$(gump init zsh)" |
| 36 | +``` |
| 37 | + |
| 38 | +**Fish** (`~/.config/fish/config.fish`) |
| 39 | +```fish |
| 40 | +gump init fish | source |
| 41 | +``` |
| 42 | + |
| 43 | +Restart shell or source the file. |
| 44 | + |
| 45 | +## Usage |
| 46 | + |
| 47 | +```bash |
| 48 | +g foo # jump to best match for "foo" |
| 49 | +g foo bar # jump to path matching "foo" then "bar" |
| 50 | +g # go home |
| 51 | +g - # go back |
| 52 | +gi foo # interactive selection with fzf |
| 53 | +``` |
| 54 | + |
| 55 | +Directories are learned automatically as you `cd` around. |
| 56 | + |
| 57 | +## Commands |
| 58 | + |
| 59 | +``` |
| 60 | +gump add <path> # manually add directory |
| 61 | +gump remove <path> # remove from database |
| 62 | +gump list # show all entries |
| 63 | +gump list --score # show entries with scores |
| 64 | +gump query <terms> # print best match (for scripts) |
| 65 | +gump clean # remove non-existent directories |
| 66 | +gump import # import from zoxide/autojump/z/fasd |
| 67 | +gump edit # edit database as JSON |
| 68 | +``` |
| 69 | + |
| 70 | +## Options |
| 71 | + |
| 72 | +```bash |
| 73 | +gump init bash --cmd j # use 'j' instead of 'g' |
| 74 | +gump init bash --hook pwd # only track on directory change (not every prompt) |
| 75 | +gump init bash --no-cmd # skip g/gi aliases, keep no-prefix jumping |
| 76 | +``` |
| 77 | + |
| 78 | +## Environment |
| 79 | + |
| 80 | +| Variable | Default | Description | |
| 81 | +|----------|---------|-------------| |
| 82 | +| `GUMP_DATA_DIR` | `~/.local/share/gump` | Database location | |
| 83 | +| `GUMP_MAXAGE` | `10000` | Max total score before aging | |
| 84 | +| `GUMP_EXCLUDE` | - | Colon-separated paths to ignore | |
| 85 | + |
| 86 | +## How it works |
| 87 | + |
| 88 | +1. Shell hook records directories on `cd` |
| 89 | +2. Frecency score = access count × recency multiplier |
| 90 | +3. Query matches terms against paths using fuzzy matching |
| 91 | +4. Unknown commands are intercepted and checked against the database |