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.

gwm wraps Git's built-in git worktree command with an interactive TUI, intuitive commands, and useful features to make worktree management effortless.

• Switch branches without stashing
• Create worktrees from remote branches instantly
• Auto-detect and remove merged worktrees
• Interactive selection with fuzzy search
• Automatic shell directory change after operations

Commands

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

Installation

Cargo

cargo install gwm

Shell integration (cd)

To automatically change your current shell directory after gwm add / gwm go, add the following to your shell config. This also enables shell completions.

# Bash (~/.bashrc)
eval "$(gwm init bash)"

# Zsh (~/.zshrc)
eval "$(gwm init zsh)"

# Fish (~/.config/fish/config.fish)
gwm init fish | source

Usage

Start working on a new branch:

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

Review a PR:

gwm add fix-bug -r -o 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/

Command Reference

gwm list (alias: ls)

List worktrees in the current project.

    BRANCH           SYNC    CHANGES  PATH                     ACTIVITY
[*] feature/new-ui   ↑2 ↓0  3M 1D    ${B}/project/feature...  2h ago
[M] main             ✓      clean    ${B}/project/main        30m ago
[-] hotfix/logfix    ↑0 ↓5  clean    ${B}/project/logfix      3d ago

STATUS meanings:

• [*]: Current worktree
• [M]: Main branches (main, master, etc.)
• [-]: Other worktrees

Column meanings:

• SYNC: Sync status with remote (↑=ahead, ↓=behind, ✓=synced)
• CHANGES: Local changes (M=Modified, D=Deleted, A=Added, U=Untracked)
• ACTIVITY: Time since last update

Options:

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:

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.

With shell integration enabled (see "Shell integration (cd)"), it changes the current shell directory. Otherwise, it launches a subshell.

• gwm go: Interactive selection (fuzzy search supported)
• gwm go feat: Filter by "feat" and select

Options:

gwm remove [query] (alias: rm)

Interactively select and remove worktrees. Supports multi-select.

Options:

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:

gwm sync (alias: pull-main)

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

Note: For backward compatibility, the legacy command name gwm pull-main is still available.

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

Configuration

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

Configuration Options

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.

Note: For backward compatibility, gwm/config.toml is also supported but .gwm/config.toml is recommended for new projects.

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:

License

MIT