GitHub and Git Worktree: The Complete Guide

Does GitHub Know I Am Using a Worktree?

No. Git worktrees are a purely local concept. When you push a branch that was created in a worktree, GitHub receives exactly the same data as if you pushed from a regular checkout. There is nothing in the push payload that distinguishes a worktree branch from a normal branch.

This means all GitHub features work identically with worktree branches: Pull Requests, branch protection rules, status checks, GitHub Actions, Codespaces, and the web editor.

Pull Request Workflow with Worktrees

The most common use of worktrees with GitHub is creating feature branches in separate directories, then pushing them to open PRs. Here is the typical flow:

# 1. Create a worktree for the feature
git worktree add ../my-project-feat feat/user-auth

# 2. Work in the worktree
cd ../my-project-feat
# ... make changes, commit ...
git add -A
git commit -m "feat: add OAuth login flow"

# 3. Push the branch to GitHub
git push -u origin feat/user-auth

# 4. Create a PR (using GitHub CLI)
gh pr create --title "Add OAuth login" --body "Implements OAuth 2.0 flow"

# 5. Done — go back to your main checkout
cd ../my-project

The advantage over the standard branch workflow: your main checkout is never interrupted. You can continue working on other features while the PR is in review.

Reviewing GitHub PRs with Worktrees

When you need to check out a PR locally for testing or review, a worktree is much faster than stashing your work and switching branches:

# Fetch the PR branch
git fetch origin pull/42/head:pr-42-review

# Create a worktree for the review
git worktree add ../pr-42-review pr-42-review

# Test it
cd ../pr-42-review
npm install && npm test

# Leave review comments on GitHub, then clean up
cd ../my-project
git worktree remove ../pr-42-review
git branch -D pr-42-review

You can have multiple PRs checked out simultaneously, each in its own worktree. This is especially useful if you are reviewing several PRs in a sprint.

Working on Multiple PRs Simultaneously

A common pain point on GitHub is having multiple PRs in flight that touch different parts of the codebase. Without worktrees, you constantly switch branches. With worktrees, each PR gets its own directory:

# PR 1: API changes
git worktree add ../project-api feat/api-v2

# PR 2: Dashboard UI
git worktree add ../project-ui feat/dashboard

# PR 3: Documentation
git worktree add ../project-docs docs/api-reference

# Push each from its own directory
cd ../project-api && git push -u origin feat/api-v2
cd ../project-ui && git push -u origin feat/dashboard
cd ../project-docs && git push -u origin docs/api-reference

# List all your active worktrees
git worktree list

GitHub Actions and Git Worktree

GitHub Actions runners can use git worktree to test multiple branches in a single job. This is useful for monorepo setups or for comparing behavior across branches:

# .github/workflows/compare-branches.yml
name: Compare branches
on: pull_request

jobs:
  compare:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Fetch full history so the base SHA is available

      - name: Create worktree for base branch
        run: |
          git worktree add ../base-branch ${{ github.event.pull_request.base.sha }}

      - name: Build both versions
        run: |
          # Build the PR version
          npm ci && npm run build

          # Build the base version
          cd ../base-branch
          npm ci && npm run build

      - name: Compare bundle sizes
        run: |
          echo "PR size: $(du -sh dist/ | cut -f1)"
          echo "Base size: $(du -sh ../base-branch/dist/ | cut -f1)"

Note: by default, actions/checkout only fetches a single commit. Worktrees need the commit or ref you want to check out to be available locally. Using fetch-depth: 0 (full history) is the simplest approach. Alternatively, you can explicitly fetch only the specific ref you need.

Branch Visibility on GitHub

Branches created in worktrees are local until you push them. Once pushed, they appear on GitHub like any other branch. A few things to keep in mind:

• Stale branches: If you create many worktree branches and push them, remember to clean up on GitHub after merging (or enable auto-delete on merge in your repo settings).
• Branch protection: Branch protection rules apply equally to worktree branches. If main requires PR review, pushing directly from a worktree to main will still be blocked.
• Naming conventions: Using prefixes like feat/, fix/, or wt/ helps teammates identify branches. This is purely convention.

GitHub Desktop and Worktrees

GitHub Desktop does not have built-in worktree support. However, you can create worktrees from the command line and then add each worktree directory as a separate repository in GitHub Desktop. Each directory will show as its own repo entry with its checked-out branch.

For a detailed walkthrough, see our GitHub Desktop worktree guide.

Frequently Asked Questions