From 15fd612cc32dcff8722787627f3c71cf4c1010dc Mon Sep 17 00:00:00 2001 From: Roo Code Date: Sun, 25 Jan 2026 14:46:15 +0000 Subject: [PATCH 1/3] docs: add worktrees feature documentation --- docs/features/worktrees.mdx | 208 ++++++++++++++++++++++++++++++++++++ sidebars.ts | 1 + 2 files changed, 209 insertions(+) create mode 100644 docs/features/worktrees.mdx diff --git a/docs/features/worktrees.mdx b/docs/features/worktrees.mdx new file mode 100644 index 00000000..80616a6e --- /dev/null +++ b/docs/features/worktrees.mdx @@ -0,0 +1,208 @@ +--- +description: Use Git worktrees to work on multiple branches simultaneously with Roo Code, each in its own VS Code window. +keywords: + - worktrees + - git worktrees + - multiple branches + - parallel development + - branch management + - agentic coding +--- + +# 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 + +:::note 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 + +:::tip 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 + +:::warning 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 +``` + +:::tip 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 diff --git a/sidebars.ts b/sidebars.ts index 3bd860da..59c2b9be 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -46,6 +46,7 @@ const sidebars: SidebarsConfig = { 'features/slash-commands', 'features/suggested-responses', 'features/task-todo-list', + 'features/worktrees', 'features/shell-integration', 'features/more-features', ], From 4aa8f29ef3a13ec36e88ac06eea4cd8e222451ff Mon Sep 17 00:00:00 2001 From: Bruno Bergher Date: Sun, 25 Jan 2026 15:01:17 +0000 Subject: [PATCH 2/3] tweaks --- docs/features/worktrees.mdx | 76 ++++--------------------------------- 1 file changed, 8 insertions(+), 68 deletions(-) diff --git a/docs/features/worktrees.mdx b/docs/features/worktrees.mdx index 80616a6e..b88d9ddd 100644 --- a/docs/features/worktrees.mdx +++ b/docs/features/worktrees.mdx @@ -39,22 +39,24 @@ You can access the worktrees feature in two ways: - Click the selector to see all your worktrees - Click on any worktree to switch to it - Click the `+` button to create a new worktree + - Click the ⚙️ to manage worktrees -2. **Settings Panel**: Navigate to Settings → Worktrees +2. **Settings Panel**: from the last point above or via Settings (⚙️) → Worktrees - View and manage all your worktrees - Create new worktrees - Delete existing worktrees - Configure `.worktreeinclude` settings + - Choose wheter to show the selector in the home screen ### Creating Your First Worktree -1. Open the Roo Code settings by clicking the gear icon +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/`) + - **Worktree Path**: Location where the worktree will be created 5. Click "Create" 6. Choose whether to open the new worktree in a new window or stay in your current window @@ -76,7 +78,7 @@ Once you have multiple worktrees, switching between them is seamless: **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 +- Click the icon to open in a new window :::tip 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. @@ -94,14 +96,7 @@ The worktrees list shows: **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 -:::warning 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 @@ -132,12 +127,6 @@ dist 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: @@ -149,59 +138,10 @@ The worktree selector can be shown or hidden from the home screen: --- -## 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 +## Tips - **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 +- **Descriptive branch names**: Use clear naming like `worktree/feature-name` to identify worktree branches later on - **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 From 91f2af7c13438a9f0fbf9d41d07373f94699d1f0 Mon Sep 17 00:00:00 2001 From: Roo Code Date: Mon, 26 Jan 2026 18:00:52 +0000 Subject: [PATCH 3/3] fix: typo, add YouTube embed and tutorial video entry for worktrees --- docs/features/worktrees.mdx | 20 +++++++++++++++++++- docs/tutorial-videos.json | 4 ++++ 2 files changed, 23 insertions(+), 1 deletion(-) diff --git a/docs/features/worktrees.mdx b/docs/features/worktrees.mdx index b88d9ddd..fac2ebdd 100644 --- a/docs/features/worktrees.mdx +++ b/docs/features/worktrees.mdx @@ -20,6 +20,24 @@ This is particularly powerful for agentic coding workflows where you might want - Run multiple tasks on different branches simultaneously - Maintain separate environments for development and debugging +
+ +
+ +
+ :::note Requirements - Git must be installed on your system - Your workspace must be a Git repository @@ -46,7 +64,7 @@ You can access the worktrees feature in two ways: - Create new worktrees - Delete existing worktrees - Configure `.worktreeinclude` settings - - Choose wheter to show the selector in the home screen + - Choose whether to show the selector in the home screen ### Creating Your First Worktree diff --git a/docs/tutorial-videos.json b/docs/tutorial-videos.json index 0ebccf62..cccb48bf 100644 --- a/docs/tutorial-videos.json +++ b/docs/tutorial-videos.json @@ -59,6 +59,10 @@ { "id": "HmnNSasv7T8", "title": "Context Management" + }, + { + "id": "BRrhcYYSh9M", + "title": "Worktrees" } ] }