|
| 1 | +--- |
| 2 | +description: Use Git worktrees to work on multiple branches simultaneously with Roo Code, each in its own VS Code window. |
| 3 | +keywords: |
| 4 | + - worktrees |
| 5 | + - git worktrees |
| 6 | + - multiple branches |
| 7 | + - parallel development |
| 8 | + - branch management |
| 9 | + - agentic coding |
| 10 | +--- |
| 11 | + |
| 12 | +# Worktrees |
| 13 | + |
| 14 | +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. |
| 15 | + |
| 16 | +This is particularly powerful for agentic coding workflows where you might want to: |
| 17 | + |
| 18 | +- Test different implementation approaches in parallel |
| 19 | +- Review pull requests without disrupting your current work |
| 20 | +- Run multiple tasks on different branches simultaneously |
| 21 | +- Maintain separate environments for development and debugging |
| 22 | + |
| 23 | +<div style={{ position: 'relative', paddingBottom: '56.25%', height: 0, overflow: 'hidden' }}> |
| 24 | + <iframe title="Worktrees Tutorial Video" |
| 25 | + src="https://www.youtube.com/embed/BRrhcYYSh9M?rel=0&modestbranding=1" |
| 26 | + style={{ |
| 27 | + position: 'absolute', |
| 28 | + top: 0, |
| 29 | + left: 0, |
| 30 | + width: '100%', |
| 31 | + height: '100%', |
| 32 | + }} |
| 33 | + frameBorder="0" |
| 34 | + allow="autoplay; encrypted-media" |
| 35 | + allowFullScreen |
| 36 | + ></iframe> |
| 37 | +</div> |
| 38 | + |
| 39 | +<div style={{ marginTop: '20px' }}></div> |
| 40 | + |
| 41 | +:::note Requirements |
| 42 | +- Git must be installed on your system |
| 43 | +- Your workspace must be a Git repository |
| 44 | +- Multi-root workspaces are not supported |
| 45 | +- Workspace must be at the repository root (not a subfolder) |
| 46 | +::: |
| 47 | + |
| 48 | +--- |
| 49 | + |
| 50 | +## Getting Started |
| 51 | + |
| 52 | +### Accessing Worktrees |
| 53 | + |
| 54 | +You can access the worktrees feature in two ways: |
| 55 | + |
| 56 | +1. **Home Screen**: When you have multiple worktrees, a worktree selector appears at the top of the chat interface |
| 57 | + - Click the selector to see all your worktrees |
| 58 | + - Click on any worktree to switch to it |
| 59 | + - Click the `+` button to create a new worktree |
| 60 | + - Click the ⚙️ to manage worktrees |
| 61 | + |
| 62 | +2. **Settings Panel**: from the last point above or via Settings (⚙️) → Worktrees |
| 63 | + - View and manage all your worktrees |
| 64 | + - Create new worktrees |
| 65 | + - Delete existing worktrees |
| 66 | + - Configure `.worktreeinclude` settings |
| 67 | + - Choose whether to show the selector in the home screen |
| 68 | + |
| 69 | +### Creating Your First Worktree |
| 70 | + |
| 71 | +1. Open the Roo Code settings by clicking the gear icon |
| 72 | +2. Navigate to the "Worktrees" section |
| 73 | +3. Click the "Create worktree" button |
| 74 | +4. Fill in the required fields: |
| 75 | + - **Base Branch**: The branch to create your new branch from (typically `main` or `develop`) |
| 76 | + - **Branch Name**: Name for the new branch (e.g., `worktree/feature-name`) |
| 77 | + - **Worktree Path**: Location where the worktree will be created |
| 78 | +5. Click "Create" |
| 79 | +6. Choose whether to open the new worktree in a new window or stay in your current window |
| 80 | + |
| 81 | +The worktree will be created with all the files from the base branch, and you can immediately start working on it. |
| 82 | + |
| 83 | +--- |
| 84 | + |
| 85 | +## Key Functionality |
| 86 | + |
| 87 | +### Switching Between Worktrees |
| 88 | + |
| 89 | +Once you have multiple worktrees, switching between them is seamless: |
| 90 | + |
| 91 | +**From the Home Screen**: |
| 92 | +- Click the worktree selector at the top of the chat |
| 93 | +- Select the worktree you want to switch to |
| 94 | +- Choose whether to switch in the current window or open a new window |
| 95 | + |
| 96 | +**From Settings**: |
| 97 | +- Navigate to Settings → Worktrees |
| 98 | +- Click on any worktree to switch to it in the current window |
| 99 | +- Click the icon to open in a new window |
| 100 | + |
| 101 | +:::tip Multiple Windows |
| 102 | +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. |
| 103 | +::: |
| 104 | + |
| 105 | +### Managing Worktrees |
| 106 | + |
| 107 | +**Viewing Your Worktrees**: |
| 108 | +The worktrees list shows: |
| 109 | +- Branch name (or "Detached HEAD" if not on a branch) |
| 110 | +- Worktree path on your filesystem |
| 111 | +- Status indicators (Primary, Locked) |
| 112 | +- Current worktree is highlighted |
| 113 | + |
| 114 | +**Deleting Worktrees**: |
| 115 | +1. Navigate to Settings → Worktrees |
| 116 | +2. Click the trash icon <Codicon name="trash" /> next to the worktree you want to delete |
| 117 | + |
| 118 | + |
| 119 | +### Copying Files with .worktreeinclude |
| 120 | + |
| 121 | +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. |
| 122 | + |
| 123 | +**How it Works**: |
| 124 | +- Create a `.worktreeinclude` file at the root of your repository |
| 125 | +- Add patterns for files/directories you want to copy (uses `.gitignore` syntax) |
| 126 | +- Files must also be in `.gitignore` to be copied (intersection of both files) |
| 127 | +- When creating a new worktree, matching files are automatically copied |
| 128 | + |
| 129 | +**Setting Up .worktreeinclude**: |
| 130 | + |
| 131 | +1. Navigate to Settings → Worktrees |
| 132 | +2. If you don't have a `.worktreeinclude` file, you'll see a message at the bottom |
| 133 | +3. Click "Create from .gitignore" to automatically create one based on your `.gitignore` |
| 134 | +4. Edit the file to include only the patterns you want to copy (e.g., `node_modules`, `.env.local`) |
| 135 | + |
| 136 | +**Example .worktreeinclude**: |
| 137 | +``` |
| 138 | +node_modules |
| 139 | +.env.local |
| 140 | +.cache |
| 141 | +dist |
| 142 | +``` |
| 143 | + |
| 144 | +:::tip What Gets Copied |
| 145 | +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. |
| 146 | +::: |
| 147 | + |
| 148 | +### Home Screen Integration |
| 149 | + |
| 150 | +The worktree selector can be shown or hidden from the home screen: |
| 151 | + |
| 152 | +1. Navigate to Settings → Worktrees |
| 153 | +2. Toggle "Show worktrees in home screen" |
| 154 | +3. When enabled, the selector appears at the top of the chat when you have multiple worktrees |
| 155 | +4. When disabled, you can still manage worktrees from Settings |
| 156 | + |
| 157 | +--- |
| 158 | + |
| 159 | +## Tips |
| 160 | + |
| 161 | +- **Organized locations**: Use a consistent location like `~/.roo/worktrees/` for all your worktrees |
| 162 | +- **Descriptive branch names**: Use clear naming like `worktree/feature-name` to identify worktree branches later on |
| 163 | +- **Regular cleanup**: Delete worktrees you're no longer using to save disk space |
| 164 | +- **Commit before deleting**: Always commit and push important changes before deleting a worktree |
| 165 | +- **Use .worktreeinclude**: Set up a `.worktreeinclude` file once and benefit from it for all future worktrees |
| 166 | +- **New windows for parallel work**: Open worktrees in new windows when you want to work on multiple branches simultaneously |
0 commit comments