git-worktree-runner (a.k.a. git-gwr) is a Go port of github.com/coderabbitai/git-worktree-runner with some additional features.

This project builds a Git subcommand binary named git-gwr (so you run it as git wr ...).

• Git installed (and new enough for git worktree).
• Go 1.25+ (only needed to build from source).

go install github.com/zchee/git-worktree-runner/cmd/git-gwr@latest

git clone https://github.com/zchee/git-worktree-runner.git
cd git-worktree-runner

make build/git-gwr

# Ensure the `git-gwr` binary is on your PATH.
# Example (macOS/Linux):
ln -sf "$(pwd)/bin/git-gwr" /usr/local/bin/git-gwr
# or
sudo ln -sf "$(pwd)/bin/git-gwr" /usr/local/bin/git-gwr

cd /path/to/your/repo

# Optional one-time setup (per repo or --global)
git wr config set gwr.editor.default cursor
git wr config set gwr.ai.default claude

# Create a worktree for a branch (creates a sibling folder by default)
git wr new feature-auth --yes

# List worktrees
git wr list
git wr list --porcelain   # path<TAB>branch<TAB>status

# Navigate (shell-friendly)
cd "$(git wr go feature-auth)"

# Run a command in a worktree directory (exit code propagates)
git wr run feature-auth git status

# Remove the worktree
git wr rm feature-auth --yes

The CLI targets upstream parity for the core UX:

• git wr new <branch> [options] — create a worktree
• git wr rm <id|branch|worktree-name>... [options] — remove worktree(s)
  • --delete-branch prompts before deleting the branch (skip prompts with --yes)
• git wr go <id|branch|worktree-name> — print absolute path to stdout
• git wr run <id|branch|worktree-name> <command...> — run command in that directory
• git wr list [--porcelain] — list main repo + worktrees
• git wr copy <target>... [options] [-- <pattern>...] — copy files between worktrees
• git wr editor <id|branch|worktree-name> [--editor <name>]
• git wr ai <id|branch|worktree-name> [--ai <name>] [-- args...]
• git wr clean — prune stale worktrees and remove empty directories in the configured base dir
• git wr doctor — basic health check
• git wr adapter — list built-in adapters and availability
• git wr config {get|set|add|unset} <key> [value] [--global]
• git wr version, git wr help

Configuration is resolved with this precedence (highest to lowest):

1. local git config (.git/config)
2. .gwrconfig (repo root, gitconfig syntax)
3. global git config (~/.gitconfig)
4. system git config
5. environment variables
6. hard-coded defaults

Common keys:

• gwr.worktrees.dir: base directory for worktrees
  • default: <repo-parent>/<repo-name>-worktrees
  • supports absolute paths, repo-relative paths, and ~ expansion
• gwr.worktrees.prefix: prefix added to each worktree folder name
• gwr.defaultBranch: auto|main|master|<branch>
• gwr.editor.default: editor adapter name or none
• gwr.ai.default: AI adapter name or none
  • cursor: prefers cursor-agent, then tries cursor cli (varies by Cursor version), then falls back to cursor
• gwr.copy.include / gwr.copy.exclude (multi): file globs for copying
• gwr.copy.includeDirs / gwr.copy.excludeDirs (multi): directory copy rules
• gwr.hook.postCreate / gwr.hook.postRemove (multi): hook commands

Environment variables supported:

• GTR_WORKTREES_DIR
• GTR_WORKTREES_PREFIX
• GTR_DEFAULT_BRANCH
• GTR_EDITOR_DEFAULT
• GTR_AI_DEFAULT

make test
make fmt
make lint

This repository uses integration-style tests (real git, real filesystem; no mocks).

Upstream ships completion scripts; this Go port includes equivalents in ./completions/:

• Zsh: completions/_git-gwr
  • Install: copy/symlink into a directory in your $fpath (example: ~/.zsh/completions/), then run autoload -Uz compinit && compinit.
• Bash: completions/gwr.bash
  • Install: add source /path/to/git-worktree-runner/completions/gwr.bash to your ~/.bashrc.
• Fish: completions/gwr.fish
  • Install: ln -s /path/to/git-worktree-runner/completions/gwr.fish ~/.config/fish/completions/ then exec fish.

Example configuration and helper scripts live under ./templates/:

• templates/.gwrconfig.example → copy to <repo-root>/.gwrconfig (gitconfig syntax)
• templates/gwr.config.example → reference for common git config keys
• templates/setup-example.sh → example one-time repo setup (git config --local ...)
• templates/run_services.example.sh → example “run multiple services” helper