gh-worktree

A GitHub CLI extension for managing git worktrees for pull requests and branches. It checks out PRs and branches using git worktree, placing worktrees outside the current repository folder, and provides commands to list, remove, and cleanup worktrees.

Worktree location

../<repository-name>-<pr-number>

For example, if you're working in ~/projects/my-app and check out PR #42, the worktree will be created at ~/projects/my-app-42.

Installation

gh extension install <owner>/gh-worktree

For local development:

gh extension install .

Usage

Create a worktree

# Check out a PR by number
gh worktree 42
gh worktree #42  # # prefix is optional

# Check out a branch
gh worktree my-feature-branch

# Explicit create command
gh worktree create 42

List worktrees

# List all worktrees with PR information
gh worktree list
gh worktree ls  # short alias

Output shows path, branch, PR number, and state (OPEN/CLOSED/MERGED):

PATH                                              BRANCH              PR      STATE
----                                              ------              --      -----
/Users/you/projects/my-app-42                    feature-auth        #42     OPEN
/Users/you/projects/my-app-99                    bugfix-login        #99     MERGED
/Users/you/projects/my-app-my-feature            my-feature          -       -

Remove a worktree

# Remove by PR number
gh worktree remove 42
gh worktree rm #42  # short alias, # prefix optional

# Remove by directory name
gh worktree remove my-app-42

# Remove by absolute path
gh worktree remove /path/to/my-app-42

# Force removal (even with uncommitted changes)
gh worktree remove --force 42
gh worktree rm -f 42

Cleanup closed/merged PR worktrees

# Remove all worktrees for closed and merged PRs
gh worktree cleanup

# Preview what would be removed (dry run)
gh worktree cleanup --dry-run
gh worktree cleanup -n

# Only remove merged PRs (not closed)
gh worktree cleanup --merged-only

# Interactive mode (prompt before each removal)
gh worktree cleanup --interactive
gh worktree cleanup -i

# Combine options
gh worktree cleanup --dry-run --merged-only

How it works

Post-create steps

After the worktree is created, the following steps run automatically if applicable:

• yarn install: if a yarn.lock file is present in the new worktree, dependencies are installed automatically.
• .vscode copy: if a .vscode folder exists in the main repository, it is copied into the new worktree so editor settings and launch configurations carry over.

Creating worktrees for PRs

When given a PR number, the create command:

1. Resolves the PR's head branch via gh pr view
2. Fetches via refs/pull/<number>/head — works with fork PRs too
3. Creates the worktree at ../<repo>-<pr-number>

Creating worktrees for branches

When given a branch name, the create command:

1. Tries to find an associated open PR (to use its number in the directory name)
2. Falls back to ../<repo>-<branch-name> if no PR is found

Managing worktrees

• List: Shows all worktrees with their associated PR status by fetching PR state from GitHub
• Remove: Deletes a worktree by PR number, directory name, or path
• Cleanup: Automatically identifies and removes worktrees for PRs that have been closed or merged

Requirements

• gh — GitHub CLI
• git with worktree support (git 2.5+)

Commands

Command	Description
gh worktree [create] <pr|branch>	Create a new worktree (default command)
gh worktree list	List all worktrees with PR status
gh worktree remove <identifier>	Remove a worktree
gh worktree cleanup	Remove worktrees for closed/merged PRs

Notes

• If the worktree directory already exists, the create command reports the path and exits — no overwriting.
• Running cd into the worktree must be done manually after the command prints the path (shell subprocesses cannot change the parent shell's directory).
• The cleanup command can automatically remove worktrees for PRs that have been closed or merged, helping keep your workspace tidy.
• Use --dry-run with cleanup to preview what would be removed before actually deleting anything.