docs: add worktrees feature documentation

Author: roomote

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 <Codicon name="gear" /> → 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 <Codicon name="gear" />
+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 <Codicon name="arrow-up-right" /> 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 <Codicon name="trash" /> 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

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',
          ],