gwm — git worktree manager

Rust CLI + ratatui TUI to manage git worktrees across projects. Native libgit2 (vendored — no gwq / git CLI dependency), per-repo + user-level configurable bootstrap (file copies, regex guards, lifecycle 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.

install

Channel	Command
Cargo (source)	cargo install --path .
cargo-binstall	cargo binstall gwm
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)

cargo binstall gwm grabs the prebuilt binary from the matching GitHub Release instead of compiling git2/vendored-libgit2 from source — no Rust toolchain needed at install time.

Full install matrix and verification steps: docs/getting-started/install.md.

the 30-second tour

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.

what gwm does

• Native worktree ops via vendored libgit2 — git worktree add/list/remove/prune without shelling out.
• CLI + ratatui TUI — gwm <subcommand> for scripts, bare gwm opens the interactive interface.
• Per-repo .gwm.toml + user-level global config — branch / path conventions, file copies, regex guards, no-symlink invariants. A ~/.config/gwm/config.toml deep-merges underneath each repo's .gwm.toml. Edit it git-config-style with gwm config get / set / list / validate.
• Lifecycle hooks [hooks.*] — pre_create / post_create / pre_bootstrap / post_bootstrap / pre_remove / post_remove phases, each with when: predicates and per-step on_fail = abort|warn|ignore.
• CLI aliases + Gitmoji convention — [aliases] expand gwm <alias> to argv before parsing; gwm commit-prefix, gwm types --gitmoji, and an opt-in gwm hooks install commit-msg hook enforce the repo's Gitmoji + Conventional Commits style.
• GitHub workflow — branches matching <type>/#<N>-<slug> auto-link to their issue (with ephemeral PR auto-detection); gwm new opens an issue from a template then spins up the worktree, gwm pr renders the PR body; live status surfaces in the TUI sidebar via gh.
• Safety daily — --dry-run on gwm remove / gwm prune to preview, gwm undo + gwm history to recover a misfired removal, a confirm-overlay countdown on armed branch-deletion, and deny-list regexes on copied files (the original "no AWS RDS in .env" incident, generalised).
• gwm sync — fetch a worktree's upstream and rebase (or --merge) its branch onto it, conflict-safe.
• Configurable launchers — drive the TUI's l (git TUI) and R (review) keybindings through [git_tui] and [review] sections in .gwm.toml.
• TUI personalisation — role-based [theme] presets (catppuccin / gruvbox / tokyo-night / claude-dark), a remappable [tui.keys] keymap with multi-key chords, a : command palette, and a sidebar stashes mode — all responsive down to a narrow terminal.
• TOFU trust ledger on .gwm.toml (#95) — first gwm create / gwm bootstrap against a repo prints the bootstrap surface (copies, guards, commands) and prompts before running anything. Recorded in ~/.config/gwm/trust.toml keyed on (origin URL, sha256 of .gwm.toml); any byte change re-prompts. CI bypass: --allow-bootstrap or GWM_ALLOW_BOOTSTRAP=1. Manage with gwm trust list / revoke / show.

documentation

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.

history

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.

license

MIT — see LICENSE.md.

related docs

• CHANGELOG.md — release index (root = [Unreleased]; per-version archives under changelogs/)
• CONTRIBUTING.md — branch / commit / PR conventions
• ROADMAP.md — long-form roadmap with grouped categories
• CODE_OF_CONDUCT.md
• .github/LABELS.md
• examples/gwm.toml.example — annotated full config
• skills/SKILL.md — the bundled Claude Code skill manifest