A git worktree wrapper with lifecycle hooks.
gw wraps git worktree with lifecycle hooks that run your scripts before and after worktree creation and removal — automating setup, teardown, and validation. It also automatically calculates worktree paths from branch names.
Design philosophy: Keep the core thin. Features that can be achieved through hooks are not built into the tool itself.
Note: Bare repositories are not supported.
Requires git 2.36 or later.
brew install gin0606/tap/gwOr with go install:
go install github.com/gin0606/gw/cmd/gw@latestThe CLI is the source of truth. The sections below in this README cover the same identifiers (hook names, env vars, config keys) for convenience and search; the authoritative documentation lives in gw help.
gw help # Root overview, including the list of topics.
gw help <command> # Same as `gw <command> --help`.
gw help hooks # Hook names, env vars, working dirs, failure modes.
gw help config # .gw/config keys and defaults.
gw help path # How worktree paths are calculated.
gw help completion # Shell completion and dynamic candidates.
gw help recipes # Shell snippets that compose with gw output.
gw help all # Everything above, in one stream.Coding agents can read the entire reference with gw help all.
gw init— Initialize.gw/directory with default configuration and hook templates.gw add <branch> [--from <ref>]— Create a new worktree. The path is calculated from the branch name and printed to stdout. When--fromis omitted and the branch does not exist, it is created fromorigin/<default branch>. It gets no upstream; pass --from to let git's usual tracking rules apply.gw rm <path> [--force]— Remove a worktree by its path (absolute or relative). Use--forceto remove even with uncommitted changes.gw list— Print the absolute path of each worktree, one per line.
Place executable files in .gw/hooks/ in your repository root. Hooks let you automate any workflow around worktree operations.
| Hook | Trigger | Working directory |
|---|---|---|
pre-add |
Before worktree creation | Repository root |
post-add |
After worktree creation | Worktree directory |
pre-remove |
Before worktree removal | Worktree directory |
post-remove |
After worktree removal | Repository root |
The following environment variables are available in hooks:
| Variable | Description |
|---|---|
GW_REPO_ROOT |
Absolute path to the main repository root |
GW_WORKTREE_PATH |
Absolute path to the worktree |
GW_BRANCH |
Branch name |
Install dependencies and copy untracked files (.gw/hooks/post-add):
#!/bin/sh
npm install
cp "$GW_REPO_ROOT/.env" "$GW_WORKTREE_PATH/.env"Stop services before removal (.gw/hooks/pre-remove):
#!/bin/sh
docker compose downDelete merged branches after removal (.gw/hooks/post-remove):
#!/bin/sh
git fetch --prune origin
if git merge-base --is-ancestor "$GW_BRANCH" origin/main 2>/dev/null; then
git branch -D "$GW_BRANCH"
fiCommands are designed to compose with standard shell tools.
# Create a worktree and cd into it
cd "$(gw add feature/user-auth)"
# Interactively select a worktree with fzf
cd "$(gw list | fzf)"
# Remove a worktree selected with fzf
gw rm "$(gw list | fzf)"Generate completion scripts with gw completion:
# Bash
gw completion bash > /etc/bash_completion.d/gw
# Zsh
gw completion zsh > "${fpath[1]}/_gw"
# Fish
gw completion fish > ~/.config/fish/completions/gw.fishTab completion is available for subcommands:
gw add <TAB>— local branch namesgw add --from <TAB>— all refs (branches, remotes, tags)gw rm <TAB>— worktree paths (excluding the main worktree)
Place a TOML configuration file at .gw/config in your repository root.
# Custom worktree base directory (absolute or relative to repository root)
worktrees_dir = "../my-worktrees"| Key | Description | Default |
|---|---|---|
worktrees_dir |
Base directory for worktrees | Adjacent to the repository |