git-nav
A fast, keyboard-driven navigator for your local git repositories.
git-nav walks a configured root, gathers status for every git repo it
finds (in parallel), and shows an inline TUI where you can filter, pick
a repo with the arrow keys, and cd into it. The picker sits at the
bottom of your terminal (like fzf) — no fullscreen takeover.

Regenerate the demo with vhs docs/demo.tape — see docs/demo.tape.
Install
Requires Rust ≥ 1.85 (for the 2024 edition).
From crates.io:
Or straight from the git repository:
Or from a local checkout:
Then wire up the shell function so cd actually happens — pick one:
Option A — automatic, appends the wrapper to your rc file (idempotent, re-run any time to refresh the baked-in path):
Option B — manual eval, add this line to your ~/.zshrc,
~/.bashrc, or ~/.config/fish/config.fish:
Both produce the exact same wrapper. A writes it to disk once, B re-evaluates it fresh on every shell start (sub-millisecond either way).
Why the shell wrapper?
A child process can't change its parent shell's directory. git-nav
prints the chosen repo path to stdout; the gnav wrapper captures it
and runs cd. If you invoke the binary directly (no wrapper), it prints
a hint pointing you at --install-shell rather than silently doing
nothing.
Configuration
On first run, git-nav prompts for the top-level directory to scan
and stores your answer at ~/.config/git-nav/config.toml
($XDG_CONFIG_HOME/git-nav/config.toml if set):
= "/Users/you/projects"
= 4
git-nav --resetre-runs the prompt.git-nav --config-pathprints the file location.git-nav --root PATHand--depth Noverride the file per-invocation.
Keys (TUI)
| Key | Action |
|---|---|
↑ / ↓ |
move selection |
PgUp / PgDn |
jump 10 rows |
Home / End |
jump to first / last |
| any printable char | narrow the fuzzy filter |
Backspace |
shrink the filter |
Enter |
pick and cd |
Esc / Ctrl-C |
quit without picking |
The filter is a case-insensitive subsequence match across REPO, ORG,
BRANCH, and AUTHOR — typing bsv matches billing-svc, typing your
own name narrows to repos you touched last.
Performance
Repo discovery and per-repo git status are parallel (rayon). On my
laptop, 50 repos with ~100 git subprocesses land in ~275ms end-to-end.
Non-TTY fallback
If stderr isn't a TTY (piped, in a script, etc.) git-nav falls back
to printing a plain table and reading a number on stdin — the original
Python-era behavior.
Development
The code lives in small modules under src/:
cli— arg parserconfig— TOML config load / save / first-run promptscanner— parallel filesystem walkgit—RepoInfo+ git subprocess calls (also parallel)ui::tui— ratatui inline selector (bottom-anchored, sized to fit)ui::render— plain-text table (non-TTY fallback)ui::fuzzy— subsequence matchershell—--initsnippets +--install-shell
License
Dual-licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE)
- MIT license (LICENSE-MIT)
at your option.