Skip to main content
Worktrees let you work on multiple branches simultaneously, each in its own folder. This enables Cline to work on tasks in parallel across separate VS Code windows, or lets Cline work independently while you continue coding in your main workspace.
Worktrees view showing multiple linked worktrees

​
What Are Git Worktrees?

A Git worktree is a linked copy of your repository in a separate folder, checked out to a specific branch. All worktrees share the same Git history and .git directory, but each has its own working directory with different code checked out. Key concepts:
  • Main worktree: Your original repository folder where the .git directory lives
  • Linked worktrees: Additional folders you create, each checked out to a different branch
  • Shared history: All worktrees share commits, branches, and Git configuration
Unlike regular branch switching, worktrees let you have multiple branches checked out at the same time in different folders. This means you can have VS Code windows open for different features simultaneously.

​
Why Use Worktrees with Cline?

Worktrees solve a common problem: Cline takes over your VS Code window while working on a task. With worktrees, you can:
  1. Run Cline in parallel - Have Cline work on multiple tasks simultaneously, each in its own worktree and VS Code window
  2. Keep working while Cline works - Let Cline handle a task in a separate worktree while you continue coding in your main workspace
  3. Isolate experimental changes - Test risky changes in a worktree without affecting your main branch
  4. Quick context switching - Jump between features without stashing or committing incomplete work

​
Getting Started

The fastest way to start using worktrees is the New Worktree Window button on Cline’s home screen:
  1. Click New Worktree Window on the home screen
  2. Enter a branch name and folder path (defaults are auto-filled)
  3. Click Create & Open
A new VS Code window opens with your worktree, and Cline automatically opens ready to work.
The home screen also shows your current branch and worktree path. Click it to open the full Worktrees view.

​
Full Worktrees View

For more control, open the full Worktrees view by clicking the Worktrees button in the Cline sidebar header, or by clicking your current branch info on the home screen:
1

Create a New Worktree

Click New Worktree at the bottom of the view. Enter a branch name and path (defaults are auto-filled).
2

Open in New Window

Once created, click the Open in new window button to open the worktree in a separate VS Code window. Cline will automatically open in the new window.

​
Typical Workflow

Here’s how a typical worktree session looks:
1

Create a new worktree

Click New Worktree Window on the home screen or use the Worktrees view. A new VS Code window opens with Cline ready to go.
2

Do your work

Work on your feature or let Cline handle a task. Make commits as you go.
3

Close the worktree window

When you’re done, close the worktree’s VS Code window.
4

Merge from your primary worktree

Back in your main VS Code window, open the Worktrees view and click the merge button on the worktree you just worked in. This merges the branch and optionally deletes the worktree.

​
Managing Worktrees

​
Viewing Worktrees

The Worktrees view shows all worktrees for your repository:
  • Current: The worktree you’re currently in (highlighted)
  • Main: The primary worktree where your .git directory lives (cannot be deleted)
  • Locked: Worktrees that are locked to prevent accidental deletion

​
Opening Worktrees

Each worktree has two open options:
  • Open in current window: Replace your current workspace with the worktree
  • Open in new window: Open the worktree in a separate VS Code window (recommended for parallel Cline sessions)
Either way, Cline automatically opens in the new workspace, ready to start a task.

​
Deleting Worktrees

Click the trash icon on any linked worktree to delete it. A confirmation dialog will show you exactly what will be deleted:
  • The branch itself
  • All project files in the worktree folder
Deleting a worktree permanently removes the branch and all files in that folder. Make sure any important changes are committed and pushed first.
You cannot delete the main worktree. It’s the primary repository where your .git directory lives.

​
Merging Worktrees

When you’re done working in a worktree and ready to merge your changes back to the main branch:
  1. Click the merge icon (git merge symbol) on any linked worktree
  2. Review the merge details in the confirmation modal
  3. Choose whether to delete the worktree after merging
  4. Click Merge
Merge worktree modal

​
Handling Merge Conflicts

If your branch has conflicts with the main branch, Cline will detect them and show you the conflicting files. You have two options:
  1. Ask Cline to Resolve & Merge - Creates a new Cline task with a prompt asking Cline to resolve the conflicts, complete the merge, and clean up the worktree
  2. Resolve Manually - Close the modal and resolve conflicts yourself using your preferred Git tools
The “Ask Cline to Resolve” option is particularly useful for complex conflicts. Cline will analyze the conflicting files and attempt to merge them intelligently based on the intent of both branches.

​
.worktreeinclude: Automatic File Copying

When you create a new worktree, it starts with a fresh checkout—no node_modules, no build artifacts, no IDE settings. This means you’d normally need to run npm install or similar setup commands. The .worktreeinclude file solves this by automatically copying specified files to new worktrees.

​
How It Works

  1. Create a .worktreeinclude file in your repository root
  2. Add glob patterns for files you want copied (using .gitignore syntax)
  3. When Cline creates a new worktree, files matching both .worktreeinclude and .gitignore are copied automatically
Only files that are both matched by .worktreeinclude AND listed in .gitignore are copied. This prevents accidentally duplicating tracked files.

​
Example .worktreeinclude

# Copy node_modules to avoid npm install
node_modules/

# Copy IDE settings
.vscode/

# Copy build cache
.next/
dist/

# Copy environment files (if gitignored)
.env.local

​
Creating a .worktreeinclude File

The Worktrees view will show a tip if you don’t have a .worktreeinclude file. If you have a .gitignore, you can click Create from .gitignore to create one pre-filled with your gitignore contents. Then edit it to keep only the patterns you want copied.
For most JavaScript/TypeScript projects, just including node_modules/ in your .worktreeinclude saves significant setup time for each new worktree.
Since .gitignore usually contains most of the files you’d want copied to new worktrees (dependencies, environment files, build caches, etc.), you can create a symlink so they stay in sync automatically: 
# In your repository root
ln -s .gitignore .worktreeinclude
Now whenever you update your .gitignore, your .worktreeinclude will have the same patterns. This is especially useful for projects where gitignored files are exactly what you want copied—no need to maintain two separate files.
If you need different patterns than your .gitignore, create a regular .worktreeinclude file instead of a symlink.

​
Best Practices

  1. Create purpose-specific worktrees - Name branches clearly (e.g., cline/refactor-auth, cline/add-tests)
  2. Open in new windows - Always use “Open in new window” for true parallelism
  3. Use .worktreeinclude - Set up automatic file copying to reduce setup time
  1. Keep your main branch clean - Use worktrees for experimental or risky changes
  2. Quick feature switches - Instead of stashing, create a worktree for interruptions
  3. Review in isolation - Create worktrees to review PRs without disrupting your work
  1. Delete unused worktrees - Remove worktrees when their branches are merged
  2. Use meaningful names - Branch names should indicate the worktree’s purpose
  3. Check for stale worktrees - Periodically review and clean up old worktrees

​
Limitations

Worktrees are not available in certain workspace configurations:
  • Multi-root workspaces: If you have multiple folders open in VS Code, worktrees are disabled. Open a single repository folder instead.
  • Subfolder of a repository: If you’ve opened a subfolder within a Git repository (not the root), worktrees are disabled. Open the repository root folder instead.
The Worktrees view will display a message explaining the limitation if either of these applies to your workspace.

​
Troubleshooting

Git doesn’t allow the same branch to be checked out in multiple worktrees. Either:
  • Use a different branch name
  • Delete the existing worktree using that branch
The path you specified already contains files. Choose a different path or delete the existing folder first.
If a worktree is locked, you’ll need to unlock it first using git worktree unlock <path> in the terminal. If the worktree has uncommitted changes, you may need to use force delete.
Make sure the files you want copied are:
  1. Listed in your .worktreeinclude file
  2. Also listed in your .gitignore (only gitignored files are copied)
  3. Actually exist in your current worktree

​
Technical Details

  • Worktrees are a native Git feature (git worktree command)
  • All worktrees share the same .git directory and object database
  • Each worktree has its own index, working directory, and HEAD
  • Worktree list is stored in .git/worktrees/
  • Each worktree contains a full checkout of the repository
  • .worktreeinclude can significantly increase worktree size (e.g., copying node_modules)
  • Consider your disk space when creating many worktrees
Worktrees are separate from Cline’s checkpoint system. Each worktree has its own checkpoint history. Checkpoints track changes within a single worktree, while worktrees let you work across multiple branches simultaneously.
Worktrees unlock true parallel development with Cline. Create a worktree, open it in a new window, and let Cline work independently while you continue coding!