Rust CLI + ratatui TUI to manage git worktrees across projects. Native libgit2 (vendored — no gwq / git CLI dependency), per-repo configurable bootstrap (file copies, regex guards, shell hooks), single binary, portable.
Full documentation lives in
docs/. This README is the landing page; every feature has a dedicated section in the doc tree.
| Channel | Command |
|---|---|
| Cargo (source) | cargo install --path . |
| Homebrew (macOS) | brew tap kbrdn1/tap && brew install gwm |
| Nix flake | nix profile install github:kbrdn1/gwm-cli |
| Prebuilt | https://github.com/kbrdn1/gwm-cli/releases (Linux / macOS / Windows) |
Full install matrix and verification steps: docs/getting-started/install.md.
cd /path/to/your/repo
gwm init # write a default .gwm.toml
gwm create feat 42 user-authentication # → ~/cc-worktree/<repo>/feat-42-user-authentication
# → branch feat/#42-user-authentication
gwm # opens the TUI on the current repo
gcd auth # fuzzy-jump into the worktree (needs `gwm shell-init`)Step-by-step walkthrough: docs/getting-started/first-worktree.md.
- Native worktree ops via vendored
libgit2—git worktree add/list/remove/prunewithout shelling out. - CLI + ratatui TUI —
gwm <subcommand>for scripts, baregwmopens the interactive interface. - Per-repo
.gwm.toml— branch / path conventions, file copies, regex guards, shell hooks, no-symlink invariants. - Configurable launchers — drive the TUI's
l(git TUI) andR(review) keybindings through[git_tui]and[review]sections in.gwm.toml. - GitHub issue / PR linking — branches matching
<type>/#<N>-<slug>auto-link to their issue; live status surfaces in the TUI sidebar viagh. - Safety guards — deny-list regexes on copied files (the original "no AWS RDS in
.env" incident, generalised), plus a confirm-overlay countdown when destructive branch-deletion is armed. - TOFU trust ledger on
.gwm.toml(#95) — firstgwm create/gwm bootstrapagainst a repo prints the bootstrap surface (copies, guards, commands) and prompts before running anything. Recorded in~/.config/gwm/trust.tomlkeyed on(origin URL, sha256 of .gwm.toml); any byte change re-prompts. CI bypass:--allow-bootstraporGWM_ALLOW_BOOTSTRAP=1. Manage withgwm trust list / revoke / show.
The full tree lives under docs/ — structured for Nuxt Content (numeric prefixes for sidebar order, frontmatter on every page) and ready to drop into the future static site.
| Section | Read this when … |
|---|---|
| Getting Started | you want to install gwm and create your first worktree |
| TUI | you live in the ratatui interface — keymap, sidebar, launchers, filter |
| CLI | you script gwm from shells, CI jobs, or gh aliases |
| Configuration | you're writing or extending .gwm.toml — bootstrap, guards, predicates |
| Integrations | you wire gwm with gh, lazygit, AI reviewers, Homebrew, Nix, or gwm doctor in CI |
| Development | you're contributing — test layout, conventions, dev shell |
| Roadmap | you want to know what shipped and what comes next |
The docs/README.md page documents the authoring conventions (frontmatter contract, numeric-prefix routing, link semantics) for anyone editing the tree.
gwm started as a Rust rewrite of tools/worktree-manager.sh — a bash script tied to one team's Laravel stack and one repo's incident history. The Rust version keeps the lessons, makes them configurable per repo, and ships as a single binary so it works in every repo without per-project shell-script copies. Full background under Development → Contributing → history.
MIT — see LICENSE.md.
CHANGELOG.md— release index (root =[Unreleased]; per-version archives underchangelogs/)CONTRIBUTING.md— branch / commit / PR conventionsROADMAP.md— long-form roadmap with grouped categoriesCODE_OF_CONDUCT.md.github/LABELS.mdexamples/gwm.toml.example— annotated full configskills/SKILL.md— the bundled Claude Code skill manifest