gwt

A git worktree manager for zsh.

Why

Git worktrees are powerful, but the workflow around them is tedious.

gwt removes the friction so that switching branches, moving WIP, and cleaning up is as easy as changing directories.

Tools like claude --worktree focus on isolated environments for agents. gwt is built for humans.

Features

• Instant branching — no setup, just switch
• Stay in the same directory — keep your working path across worktrees
• Bring WIP with you — carry uncommitted changes across branches
• Terminal integration — display the current branch in your terminal
• Easy cleanup — prune or bulk delete worktrees and branches
• Share files — symlink files into every worktree
• Per-repo hooks — automate setup, teardown, and more
• Works with git — falls through to git worktree when needed

Requirements

• zsh
• git
• gum — interactive prompts, filtering, and spinners (brew install gum)

Installation

Clone the repository and source gwt.sh.

git clone https://github.com/davidv1213/gwt.git ~/gwt
echo 'source ~/gwt/gwt.sh' >> ~/.zshrc
source ~/gwt/gwt.sh

Completions are loaded automatically.

Quick start

gwt create feat/auth          # new worktree + branch from origin/main
gwt go                        # interactive picker to switch worktrees
gwt go main                   # jump back to main worktree
gwt delete                    # delete current worktree + branch
gwt delete feat/auth feat/nav # delete multiple by branch name
gwt cleanup                   # interactive bulk delete

Transfer dirty state between worktrees:

gwt create -w bugfix/nav      # stash WIP, branch from HEAD, pop in new worktree
gwt go -wt feat/auth          # stash WIP, switch worktree, update window title

Run gwt --help for the full command reference, or gwt <command> --help for details on any command. Other commands will be passed directly to git worktree.

Configuration

Global configuration is via environment variables. Per-repo behaviour can be added with hooks.

Variable	Default	Description
GWT_BASE_PATH_TEMPLATE	../.gwt-{{REPO}}	Worktree location relative to repo root. {{REPO}} is replaced with the repo name.
GWT_MIRROR_PATHS	(unset)	Space-separated paths to symlink from main worktree into new ones (e.g. .claude .env.local)
GWT_WINDOW_TITLE	false	Default for --title flag
GWT_PROMPT_WIP	create	Subcommands that prompt on dirty state. Comma-separated, or true/false.

Hooks

gwt looks for an executable .gwt-hooks file in your repository root. This is useful for project-specific setup (like npm install or direnv allow).

The script receives the event name as $1 and runs in a subshell. Some commonly used events:

Event	Timing
post-create	After a new worktree is created
post-checkout	After checking out a branch into a new worktree
post-go	After switching to a worktree
pre-delete	Before a worktree is removed

All commands support pre-<command> and post-<command> events.

Environment variables available in the hook:

Variable	Description
GWT_HOOK_MAIN_WT	Path to the main worktree
GWT_HOOK_TARGET_WT	Path to the target worktree (if applicable)
GWT_HOOK_BRANCH	Branch name (if applicable)

Example

#!/bin/bash
case "$1" in
    post-create|post-checkout)
        cd "$GWT_HOOK_TARGET_WT" && npm install
        ;;
esac

chmod +x .gwt-hooks

Uninstall

Remove the source line from your .zshrc and delete the gwt directory.

License

MIT