GitHub Desktop and Git Worktree

Does GitHub Desktop Support Worktrees?

As of now, GitHub Desktop does not have native worktree support. There is no built-in UI for creating, listing, or managing worktrees. If you open a linked worktree directory in GitHub Desktop, it may behave unpredictably or fail to recognize the repository structure correctly.

The core limitation is that GitHub Desktop expects a traditional .git directory at the root of each repository. In a linked worktree, the .git entry is a file (not a directory) that points back to the main repository's git directory. While git itself handles this transparently, GitHub Desktop's internal repository detection does not fully account for this pattern.

This has been a community-requested feature for several years. The GitHub Desktop team has acknowledged the request, but there is no confirmed timeline for when native worktree support might be added.

Workarounds for Using Worktrees with GitHub Desktop

While GitHub Desktop cannot manage worktrees directly, you can use a combination of the terminal and GitHub Desktop to get a workable workflow.

Step 1: Create Worktrees from the Terminal

Use the command line to create and manage your worktrees. This is the standard git worktree add workflow:

# Navigate to your main repository
cd ~/Projects/my-repo

# Create a worktree for a feature branch
git worktree add ../my-repo-feature feat/new-feature

# Create a worktree for a hotfix
git worktree add ../my-repo-hotfix hotfix/critical-bug

Step 2: Add Each Worktree as a Separate Repository

In GitHub Desktop, use File > Add Local Repository and point it to the worktree directory. GitHub Desktop will treat it as a separate repository. You can then view changes, stage files, and commit from the GUI. This workaround has some caveats:

• GitHub Desktop may show warnings about the repository structure. These are generally safe to ignore.
• Branch switching within GitHub Desktop should be avoided for linked worktrees, as each worktree is tied to a specific branch. Use the terminal for any branch management.
• Some operations like fetching and pulling work normally since they operate on the shared git objects.

# After adding the worktree directory in GitHub Desktop,
# you can still manage worktrees from the terminal:

# List all worktrees
git worktree list

# Remove a worktree when done
git worktree remove ../my-repo-feature

Viewing Diffs and Staging Changes

Once a worktree is added as a repository in GitHub Desktop, you can use its diff viewer and commit interface normally. The staged/unstaged file views, line-by-line staging, and commit history all work as expected. This gives you the visual diff experience of GitHub Desktop combined with the branch isolation of git worktrees.

Alternative Tools with Better Worktree Support

If you rely heavily on worktrees, consider using a Git client that offers native support:

Feature Request Status

The request for git worktree support in GitHub Desktop has been tracked in the GitHub Desktop repository on GitHub. The issue has received significant community engagement with upvotes and comments from users who want this feature. Key points from the discussion:

• The feature request asks for the ability to create, switch between, and remove worktrees from within GitHub Desktop.
• Some contributors have pointed out that worktree support would require changes to how GitHub Desktop detects and opens repositories.
• The GitHub Desktop team has not committed to a specific release for this feature, but it remains an open request.

If worktree support in GitHub Desktop is important to you, upvoting the feature request on GitHub helps signal demand. In the meantime, the terminal-based workaround described above provides a functional, if imperfect, solution.