Skip to main content

Worktrees

Git worktrees allow you to work on multiple branches of the same repository simultaneously by keeping them in different directories. Each worktree gets its own VS Code window with Roo Code, enabling parallel development without branch switching.

This is particularly powerful for agentic coding workflows where you might want to:

  • Test different implementation approaches in parallel
  • Review pull requests without disrupting your current work
  • Run multiple tasks on different branches simultaneously
  • Maintain separate environments for development and debugging
Requirements
  • Git must be installed on your system
  • Your workspace must be a Git repository
  • Multi-root workspaces are not supported
  • Workspace must be at the repository root (not a subfolder)

Getting Started​

Accessing Worktrees​

You can access the worktrees feature in two ways:

  1. Home Screen: When you have multiple worktrees, a worktree selector appears at the top of the chat interface

    • Click the selector to see all your worktrees
    • Click on any worktree to switch to it
    • Click the + button to create a new worktree

  2. Settings Panel: Navigate to Settings → Worktrees

    • View and manage all your worktrees
    • Create new worktrees
    • Delete existing worktrees
    • Configure .worktreeinclude settings

Creating Your First Worktree​

  1. Open the Roo Code settings by clicking the gear icon
  2. Navigate to the "Worktrees" section
  3. Click the "Create worktree" button
  4. Fill in the required fields:
    • Base Branch: The branch to create your new branch from (typically main or develop)
    • Branch Name: Name for the new branch (e.g., worktree/feature-name)
    • Worktree Path: Location where the worktree will be created (suggested path is ~/.roo/worktrees/)
  5. Click "Create"
  6. Choose whether to open the new worktree in a new window or stay in your current window

The worktree will be created with all the files from the base branch, and you can immediately start working on it.

Key Functionality​

Switching Between Worktrees​

Once you have multiple worktrees, switching between them is seamless:

From the Home Screen:

  • Click the worktree selector at the top of the chat
  • Select the worktree you want to switch to
  • Choose whether to switch in the current window or open a new window

From Settings:

  • Navigate to Settings → Worktrees
  • Click on any worktree to switch to it in the current window
  • Click the icon to open in a new window
Multiple Windows

Opening worktrees in new windows allows you to have multiple tasks running in parallel, each in its own workspace. This is ideal for comparing different approaches or working on multiple features simultaneously.

Managing Worktrees​

Viewing Your Worktrees: The worktrees list shows:

  • Branch name (or "Detached HEAD" if not on a branch)
  • Worktree path on your filesystem
  • Status indicators (Primary, Locked)
  • Current worktree is highlighted

Deleting Worktrees:

  1. Navigate to Settings → Worktrees
  2. Click the trash icon next to the worktree you want to delete
  3. Review the warning - deletion will remove:
    • The branch and any uncommitted changes
    • All files in the worktree directory
  4. Confirm deletion
Deletion is Permanent

Deleting a worktree removes the branch and all files in that directory. Make sure to commit and push any important changes before deleting.

Copying Files with .worktreeinclude​

By default, Git worktrees only include files tracked by Git. Untracked files like node_modules, .env, or build artifacts aren't copied. The .worktreeinclude feature solves this problem.

How it Works:

  • Create a .worktreeinclude file at the root of your repository
  • Add patterns for files/directories you want to copy (uses .gitignore syntax)
  • Files must also be in .gitignore to be copied (intersection of both files)
  • When creating a new worktree, matching files are automatically copied

Setting Up .worktreeinclude:

  1. Navigate to Settings → Worktrees
  2. If you don't have a .worktreeinclude file, you'll see a message at the bottom
  3. Click "Create from .gitignore" to automatically create one based on your .gitignore
  4. Edit the file to include only the patterns you want to copy (e.g., node_modules, .env.local)

Example .worktreeinclude:

node_modules
.env.local
.cache
dist
What Gets Copied

Only files that match BOTH .worktreeinclude AND .gitignore patterns are copied. This ensures you're only copying untracked files that you intentionally want to duplicate across worktrees.

Copy Progress: When creating a worktree with a .worktreeinclude file:

  • A progress indicator shows which files are being copied
  • Large directories like node_modules are copied with real-time progress updates
  • The operation continues in the background if you close the modal

Home Screen Integration​

The worktree selector can be shown or hidden from the home screen:

  1. Navigate to Settings → Worktrees
  2. Toggle "Show worktrees in home screen"
  3. When enabled, the selector appears at the top of the chat when you have multiple worktrees
  4. When disabled, you can still manage worktrees from Settings

Use Cases​

Parallel Feature Development​

Create separate worktrees for different features:

  • Base worktree on main for production hotfixes
  • Feature worktree for new development
  • Experimental worktree for trying new approaches

Switch between them instantly without stashing or committing incomplete work.

Code Review Workflow​

Review pull requests without disrupting your current work:

  1. Create a worktree from the PR branch
  2. Open it in a new window
  3. Test and review the changes
  4. Delete the worktree when done

Testing Different Implementations​

Try multiple solutions to the same problem:

  1. Create worktrees for different approaches
  2. Run tasks in parallel with Roo Code
  3. Compare results
  4. Keep the best implementation and delete the others

Environment Isolation​

Maintain separate environments with different dependencies:

  • Development worktree with latest dependencies
  • Stable worktree with pinned versions
  • Testing worktree with experimental packages

Each worktree can have its own node_modules copied via .worktreeinclude.

Limitations​

  • Single-root workspaces only: Multi-root workspaces are not supported
  • Repository root required: Workspace must be at the Git repository root, not a subfolder
  • Git required: Git must be installed on your system
  • Task isolation: Only one task can run per worktree at a time
  • Branches in use: Branches already checked out in other worktrees cannot be used for new worktrees
  • Primary worktree: The original repository worktree (marked as "Primary") cannot be deleted

Tips and Best Practices​

  • Organized locations: Use a consistent location like ~/.roo/worktrees/ for all your worktrees
  • Descriptive branch names: Use clear naming like worktree/feature-name to identify worktree branches
  • Regular cleanup: Delete worktrees you're no longer using to save disk space
  • Commit before deleting: Always commit and push important changes before deleting a worktree
  • Use .worktreeinclude: Set up a .worktreeinclude file once and benefit from it for all future worktrees
  • New windows for parallel work: Open worktrees in new windows when you want to work on multiple branches simultaneously