How to Use Git Worktrees with GitHub Copilot CLI

Git worktrees allow you to work on multiple branches simultaneously without switching branches or stashing changes. GitHub Copilot CLI supports worktrees, enabling parallel AI-assisted development across different features or experiments.

What Are Git Worktrees?

Git worktrees let you check out multiple branches of a repository into separate directories at the same time. Instead of constantly switching branches, you can have:

• main-worktree/ - Your main working directory
• feature-auth-worktree/ - Working on authentication feature
• bugfix-api-worktree/ - Fixing an API bug

Each worktree has its own working directory and index, but they share the same Git history and objects.

Prerequisites

Before setting up worktrees with Copilot CLI, ensure you have:

• Git 2.5 or higher (worktrees were introduced in Git 2.5)
• GitHub Copilot CLI installed (installation guide)
• Active Copilot subscription (Individual, Business, or Enterprise)
• VS Code (optional, for background agent integration)

Check your Git version:

git --version

Setting Up Git Worktrees

macOS and Linux

Create a dedicated directory for your worktrees and set up your first worktree:

# Navigate to your repository
cd ~/projects/my-repo

# Create a directory to organize worktrees
mkdir -p ~/worktrees/my-repo

# Create a worktree for a feature branch
git worktree add ~/worktrees/my-repo/feature-auth feature/auth

# Create a worktree for an existing branch
git worktree add ~/worktrees/my-repo/develop develop

# Create a worktree with a new branch
git worktree add -b feature/new-api ~/worktrees/my-repo/new-api main

Windows (PowerShell)

# Navigate to your repository
cd C:\Projects\my-repo

# Create a directory to organize worktrees
New-Item -ItemType Directory -Force -Path C:\Worktrees\my-repo

# Create a worktree for a feature branch
git worktree add C:\Worktrees\my-repo\feature-auth feature/auth

# Create a worktree for an existing branch
git worktree add C:\Worktrees\my-repo\develop develop

# Create a worktree with a new branch
git worktree add -b feature/new-api C:\Worktrees\my-repo\new-api main

List and Remove Worktrees

# List all worktrees
git worktree list

# Remove a worktree (from any worktree directory)
git worktree remove ~/worktrees/my-repo/feature-auth

# Prune stale worktree references
git worktree prune

Using Copilot CLI in Worktrees

Basic Usage

Navigate to any worktree directory and start Copilot CLI as normal:

# Navigate to a worktree
cd ~/worktrees/my-repo/feature-auth

# Start Copilot CLI
copilot

Each worktree operates as an independent workspace. Copilot CLI automatically recognizes the repository context and branch you are working on.

Establishing Directory Trust

When you first run Copilot CLI in a new worktree, you may need to establish directory trust before Copilot can execute commands:

# Start Copilot CLI
copilot

# If prompted, confirm trust for this directory
> /trust

Alternatively, pre-trust the directory:

copilot --trust-dir ~/worktrees/my-repo/feature-auth

Independent Sessions Per Worktree

Each worktree can maintain its own Copilot CLI session. This enables workflows like:

# Terminal 1: Working on authentication
cd ~/worktrees/my-repo/feature-auth
copilot
> Help me implement OAuth2 login

# Terminal 2: Working on API fixes (simultaneously)
cd ~/worktrees/my-repo/bugfix-api
copilot
> Debug why the /users endpoint returns 500

VS Code Background Agent Integration

VS Code's Copilot extension includes background agents that can automatically create and manage worktrees for isolated task execution.

Enabling Worktree Isolation Mode

1. Open VS Code Settings (Cmd+, on macOS, Ctrl+, on Windows/Linux)
2. Search for "Copilot background agent"
3. Set Isolation Mode to "Worktree"

Or add to your settings.json:

{
  "github.copilot.chat.agent.isolationMode": "worktree"
}

How Worktree Isolation Works

When you delegate a task to a background agent with worktree isolation:

1. VS Code creates a new worktree automatically
2. The agent works in the isolated worktree
3. Changes are made without affecting your current workspace
4. You review and merge changes when the agent completes

This is particularly useful for:

• Long-running refactoring tasks
• Experimental implementations
• Tasks that might conflict with your current work

Starting a Background Agent Task

In VS Code with Copilot Chat:

/delegate Refactor the authentication module to use JWT tokens

The agent creates a worktree, makes changes, and opens a pull request when finished.

Configuration File Behavior

Copilot CLI configuration files are shared across all worktrees since they exist at the repository level:

This means:

• Custom agents defined in .github/agents/ work in all worktrees
• Repository-specific instructions in copilot-instructions.md apply everywhere
• You do not need to duplicate configuration per worktree

Worktree-Specific Overrides

If you need different behavior in a specific worktree, you can create a local configuration:

# In a specific worktree
cd ~/worktrees/my-repo/experimental
echo "Allow more aggressive refactoring in this experimental branch" > .copilot-local

Note: .copilot-local files are not officially supported but can be referenced in your prompts.

Known Limitations

Session Corruption in Long Sessions

There is a known issue (GitHub Issue #1050) where Copilot CLI sessions can become corrupted during long, tool-heavy sessions in worktree directories. Symptoms include:

• Unexpected errors or crashes
• Commands failing that previously worked
• Context appearing lost

Workaround: Start fresh sessions periodically rather than maintaining extremely long-running sessions.

# If experiencing issues, exit and restart
exit
copilot

Subagents Not Available

As of January 2025, subagent functionality is not yet available in the Public Preview. This means you cannot delegate tasks from one agent to another within a worktree session.

No Built-in Worktree Management

The standalone Copilot CLI does not include commands to create or manage worktrees. Use standard Git commands for worktree operations, then use Copilot CLI within those directories.

Best Practices

1. Organize Worktrees in a Dedicated Directory

Keep all worktrees for a repository in one location:

~/worktrees/
  my-repo/
    feature-auth/
    feature-api/
    bugfix-login/
  another-repo/
    main/
    develop/

This makes it easy to find worktrees and prevents cluttering your projects directory.

2. Start Fresh Sessions Per Worktree

Rather than trying to continue sessions across worktrees, start fresh:

# Bad: Trying to resume in a different worktree
cd ~/worktrees/my-repo/feature-auth
copilot --resume  # May have wrong context

# Good: Start fresh in each worktree
cd ~/worktrees/my-repo/feature-auth
copilot  # Clean session with correct context

3. Trust Each Worktree Explicitly

When setting up a new worktree for Copilot CLI usage:

cd ~/worktrees/my-repo/new-feature
copilot --trust-dir .

This prevents trust prompts from interrupting your workflow later.

4. Use Descriptive Worktree Names

Name worktrees to match their branch or purpose:

# Good: Clear purpose
git worktree add ~/worktrees/my-repo/auth-oauth feature/auth-oauth
git worktree add ~/worktrees/my-repo/perf-testing performance/load-tests

# Avoid: Generic names
git worktree add ~/worktrees/my-repo/test1 feature/something

5. Clean Up Stale Worktrees

Regularly prune worktrees you are no longer using:

# List all worktrees
git worktree list

# Remove completed feature worktrees
git worktree remove ~/worktrees/my-repo/feature-completed

# Clean up any stale references
git worktree prune

Troubleshooting

Copilot CLI Not Recognizing Repository

If Copilot CLI does not recognize you are in a Git repository:

1. Verify the worktree was created correctly:

git worktree list

2. Check that .git file exists and points to the main repository:

cat .git
# Should show: gitdir: /path/to/main/repo/.git/worktrees/name

3. Ensure the main repository is accessible

Trust Prompts Keep Appearing

If you keep getting trust prompts in the same worktree:

1. Run the trust command explicitly:

copilot --trust-dir $(pwd)

2. Check that the path is consistent (no symlinks causing different paths)

3. Verify your Copilot CLI configuration directory has write permissions

Changes Not Appearing in Other Worktrees

Remember that worktrees share Git history but have independent working directories. To see changes from another worktree:

# From any worktree, fetch and merge/rebase as normal
git fetch origin
git merge origin/feature-auth

Next Steps

• Learn about Copilot CLI agents for specialized tasks
• Explore slash commands for efficient workflows
• Set up AGENTS.md configuration for team standards
• Try Claude Code CLI for another AI coding assistant with worktree support