Worktrees

What are git worktrees?

A git worktree is an additional working directory linked to the same repository. Each worktree has its own checked-out branch, but they all share the same .git directory. This means you can work on multiple branches simultaneously without stashing or cloning.

How gwt manages worktrees

gwt stores worktrees in .worktrees/ (configurable via worktree.path). Branch names are sanitized for filesystem use — feat/my-feature becomes .worktrees/feat-my-feature/.

Creating

gwt create feat/my-feature

Creates the worktree and runs post-create hooks. If you have hooks configured (like npm ci), they run automatically in the new worktree.

Switching

gwt switch feat/my-feature

If the worktree doesn’t exist yet, gwt auto-creates it (when worktree.auto-create is enabled, which is the default). Inside a Zellij session, the tab switches automatically. Outside Zellij, it prints the worktree path.

Removing

gwt remove feat/my-feature

Runs pre-remove hooks (Zellij closes the tab, gateway stops apps), removes the worktree directory, and deletes the branch (unless --keep-branch is passed).

You cannot remove the worktree you’re currently in — switch to a different one first.

Listing

gwt list

Shows all worktrees with the current one marked:

  * main                 /path/to/project
    feat/my-feature      /path/to/project/.worktrees/feat-my-feature
    fix/bug-123          /path/to/project/.worktrees/fix-bug-123

Configuration

See worktree configuration for available options.