English | 日本語

gwm – Git Worktree Manager

A CLI tool for managing Git worktrees, allowing you to work on multiple branches simultaneously.

What problem does gwm solve?

When reviewing multiple PRs or working on a hotfix while developing another feature, you end up running git stash and git checkout repeatedly. gwm uses Git's worktree feature to manage separate directories for each branch.

• Switch branches without stashing
• Create worktrees from remote branches instantly
• Auto-detect and remove merged worktrees

Commands

Command	Description
gwm list / gwm ls	List worktrees
gwm add	Create a new worktree
gwm go	Jump to a worktree or open in VS Code/Cursor
gwm remove / gwm rm	Remove worktrees
gwm clean	Detect and remove merged worktrees
gwm pull-main	Run git pull in main worktrees

Run gwm help <command> for details on each command.

Installation

npm install -g @shutootaki/gwm

# Try without installing
npx @shutootaki/gwm

Usage

Start working on a new branch:

gwm add feature/new-login --code    # Create worktree and open in VS Code

Review a PR:

gwm add fix-bug -r --code    # Create worktree from remote branch and open in VS Code
# After review
gwm remove fix-bug           # Remove it

Clean up old worktrees:

gwm clean                    # Detect and remove merged worktrees

Directory Layout

Worktrees are created at:

~/git-worktrees/<repository-name>/<branch-name>/

Example: ~/git-worktrees/my-app/feature-login/

Configuration

Customize behavior in ~/.config/gwm/config.toml.

Configuration Options

Option	Description	Default
worktree_base_path	Directory to create worktrees	~/git-worktrees
main_branches	Branch names treated as main branches	["main", "master"]
clean_branch	Delete local branch when removing worktree	"ask"
copy_ignored_files.enabled	Copy gitignored files to new worktrees	false
copy_ignored_files.patterns	File patterns to copy	[]
copy_ignored_files.exclude_patterns	File patterns to exclude from copying	[]
hooks.post_create.enabled	Run hooks after worktree creation	true
hooks.post_create.commands	Commands to run after creation	[]

clean_branch values:

• "auto": Auto-delete if safe
• "ask": Prompt for confirmation (default)
• "never": Never delete

Example Configuration

worktree_base_path = "/Users/me/worktrees"
clean_branch = "ask"

[copy_ignored_files]
enabled = true
patterns = [".env", ".env.*", ".env.local"]
exclude_patterns = [".env.example", ".env.sample"]

[hooks.post_create]
commands = ["npm install"]

Project-specific Configuration

Create gwm/config.toml in your repository for project-specific settings. Project settings override global settings.

Example: Use pnpm for this project

my-project/gwm/config.toml:

[hooks.post_create]
commands = ["pnpm install"]

Hook Environment Variables

The following environment variables are available during post_create hooks:

Variable	Description
GWM_WORKTREE_PATH	Absolute path to the new worktree
GWM_BRANCH_NAME	Branch name
GWM_REPO_ROOT	Git repository root path
GWM_REPO_NAME	Repository name

Command Reference

gwm list (alias: ls)

List worktrees in the current project.

STATUS  BRANCH            PATH                              HEAD
*       feature/new-ui    /Users/me/project                 a1b2c3d
M       main              ~/git-worktrees/project/main      123abc4
-       hotfix/logfix     ~/git-worktrees/project/logfix    c7d8e9f

STATUS meanings:

• * ACTIVE: Current worktree
• M MAIN: Main branches (main, master, etc.)
• - OTHER: Other worktrees

---

gwm add [branch_name]

Create a new worktree.

Without arguments (gwm add):

• Opens interactive UI for entering a new branch name
• Press Tab to switch to remote branch selection mode

With arguments:

• gwm add feature/new-login: Create new branch and worktree
• gwm add existing-branch: Create worktree from existing local branch
• gwm add pr-branch -r: Create worktree from remote branch

Options:

Option	Description
-r, --remote	Create from remote branch
--from <branch>	Base branch (default: main or master)
--code	Open in VS Code after creation
--cursor	Open in Cursor after creation
--cd	Change to worktree directory (for shell integration)
--skip-hooks	Skip post_create hooks execution

Automatic file copying:

When copy_ignored_files is enabled, .env files are automatically copied from the main worktree to the new worktree.

---

gwm go [query]

Select a worktree and jump to it (launches a subshell).

• gwm go: Interactive selection
• gwm go feat: Filter by "feat" and select

Options:

Option	Description
-c, --code	Open in VS Code
--cursor	Open in Cursor

---

gwm remove [query] (alias: rm)

Interactively select and remove worktrees. Supports multi-select.

Options:

Option	Description
-f, --force	Force delete even with uncommitted changes
--clean-branch <mode>	Delete local branch too (auto / ask / never)

---

gwm clean

Auto-detect and remove worktrees that are safe to delete.

A worktree is eligible if:

1. Remote branch is deleted or merged into main
2. No uncommitted or unpushed local changes
3. Not a main branch or the current worktree

Options:

Option	Description
-n, --dry-run	Show list only, don't delete
--force	Delete without confirmation

---

gwm pull-main

Find main branch worktrees (main, master, etc.) and run git pull to update them. Works from any directory.

Workflow Comparison

Traditional Git

# Reviewing a PR
git stash                    # Save current work
git checkout main            # Switch to main
git pull                     # Update main
git checkout pr-branch       # Switch to PR branch
git pull origin pr-branch    # Update PR branch
# ... review work ...
git checkout main            # Back to main
git stash pop                # Restore work

With gwm

# Reviewing a PR
gwm add pr-branch -r         # Create worktree from remote
gwm go pr-branch             # Jump to review worktree
# ... review work ... (original work untouched)
gwm remove pr-branch         # Remove when done

Help

• gwm help: General help
• gwm help <command>: Command-specific help
• GitHub Issues: Bug reports and feature requests

License

MIT