Skip to content

Commit 128b2a2

Browse files
hannesrudolphhannesrudolph
committed
feat: add documentation for experimental Concurrent File Edits feature
1 parent f9a77fb commit 128b2a2

File tree

3 files changed

+191
-1
lines changed

3 files changed

+191
-1
lines changed

‎docs/advanced-usage/available-tools/apply-diff.md‎

Lines changed: 70 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -102,4 +102,73 @@ Example format for the `<diff>` block:
102102
const defaultTimeout = 5000;
103103
=======
104104
const defaultTimeout = 10000; // Increased timeout
105-
>>>>>>> REPLACE
105+
>>>>>>> REPLACE
106+
```
107+
108+
---
109+
110+
## Experimental: Multi-File Edits (`MULTI_FILE_APPLY_DIFF`)
111+
112+
An experimental version of `apply_diff` allows for applying changes to multiple files within a single tool call. This feature is activated by the `MULTI_FILE_APPLY_DIFF` experiment flag.
113+
114+
### Key Features of Experimental Mode
115+
116+
- **Multi-File Operations**: Edit multiple files in one request, streamlining complex refactoring tasks.
117+
- **Batch Approval UI**: When multiple files are targeted, a single UI appears for the user to approve or deny all changes at once, or manage permissions for each file individually.
118+
- **New XML Format**: Introduces a new, more structured XML format using `<args>` and `<file>` tags to handle multiple operations.
119+
- **Backward Compatibility**: The experimental tool remains compatible with the legacy single-file `path` and `diff` parameter format.
120+
121+
### How It Works (Experimental)
122+
123+
1. **Experiment Check**: The tool first checks if the `MULTI_FILE_APPLY_DIFF` experiment is enabled. If not, it falls back to the legacy `apply_diff` implementation.
124+
2. **Parameter Parsing**: It parses the new `<args>` XML format to identify all target files and their corresponding diff operations. It can also handle the legacy `path`/`diff` parameters.
125+
3. **Validation and Approval**:
126+
* It validates that all target files exist and are accessible (not blocked by `.rooignore`).
127+
* If multiple files are being modified, it presents a **batch approval** dialog to the user.
128+
4. **Diff Application**: For each approved file, it applies the specified diffs using the `MultiFileSearchReplaceDiffStrategy`. This strategy can apply multiple, non-overlapping changes to a single file.
129+
5. **Results**: It returns a consolidated result message summarizing the outcome for all attempted operations.
130+
131+
### New Diff Format (Experimental)
132+
133+
The experimental mode uses a new XML structure within the `<apply_diff>` tool call.
134+
135+
- **`<args>`**: A container for all file operations.
136+
- **`<file>`**: A block for each file to be modified. Contains `<path>` and one or more `<diff>` tags.
137+
- **`<path>`**: The relative path to the file.
138+
- **`<diff>`**: A block containing the change.
139+
- **`<content>`**: The `SEARCH/REPLACE` block.
140+
- **`<start_line>`**: (Optional) A line number hint.
141+
142+
**Example: Modifying two files in one call**
143+
144+
```xml
145+
<apply_diff>
146+
<args>
147+
<file>
148+
<path>src/services/auth.service.ts</path>
149+
<diff>
150+
<content>
151+
<<<<<<< SEARCH
152+
:start_line:50
153+
-------
154+
const token_expiration = '15m';
155+
>>>>>>> REPLACE
156+
</content>
157+
</diff>
158+
</file>
159+
<file>
160+
<path>src/config/auth.config.ts</path>
161+
<diff>
162+
<content>
163+
<<<<<<< SEARCH
164+
:start_line:12
165+
-------
166+
rateLimit: 5,
167+
=======
168+
rateLimit: 10,
169+
>>>>>>> REPLACE
170+
</content>
171+
</diff>
172+
</file>
173+
</args>
174+
</apply_diff>

‎docs/features/experimental/concurrent-file-edits.md‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
# Concurrent File Edits
2+
3+
Edit multiple files in a single operation, dramatically speeding up refactoring and multi-file changes.
4+
5+
---
6+
7+
## What It Does
8+
9+
Concurrent File Edits allows Roo to modify multiple files in your workspace within a single request. Instead of approving each file edit individually, you review and approve all changes at once through a unified batch approval interface.
10+
11+
---
12+
13+
## Why Use It
14+
15+
**Traditional approach**: Sequential file edits requiring individual approvals
16+
- Edit file A → Approve
17+
- Edit file B → Approve
18+
- Edit file C → Approve
19+
20+
**With Concurrent File Edits**: All changes presented together
21+
- Review all proposed changes across files A, B, and C
22+
- Approve once to apply all changes
23+
24+
This reduces interruptions and speeds up complex tasks like:
25+
- Refactoring functions across multiple files
26+
- Updating configuration values throughout your codebase
27+
- Renaming components and their references
28+
- Applying consistent formatting or style changes
29+
30+
---
31+
32+
## How to Enable
33+
34+
1. Open VS Code Settings (Cmd/Ctrl + ,)
35+
2. Search for "experimental.MULTI_FILE_APPLY_DIFF"
36+
3. Enable the setting
37+
4. Restart VS Code for changes to take effect
38+
39+
Or add to your settings.json:
40+
```json
41+
{
42+
"roo.experimental.MULTI_FILE_APPLY_DIFF": true
43+
}
44+
```
45+
46+
---
47+
48+
## Using the Feature
49+
50+
When enabled, Roo automatically uses concurrent edits when appropriate. You'll see a "Batch Diff Approval" interface showing:
51+
52+
- All files to be modified
53+
- Proposed changes for each file
54+
- Options to approve all changes or review individually
55+
56+
### Example Workflow
57+
58+
1. Ask Roo to "Update all API endpoints to use the new authentication method"
59+
2. Roo analyzes your codebase and identifies all affected files
60+
3. You receive a single batch approval request showing changes across:
61+
- `src/api/users.js`
62+
- `src/api/products.js`
63+
- `src/api/orders.js`
64+
- `src/middleware/auth.js`
65+
4. Review all changes in the unified diff view
66+
5. Approve to apply all changes simultaneously
67+
68+
---
69+
70+
## Technical Details
71+
72+
This feature leverages the [`apply_diff`](/advanced-usage/available-tools/apply-diff#experimental-multi-file-edits-multi_file_apply_diff) tool's experimental multi-file capabilities. For detailed information about the implementation, XML format, and how the `MultiFileSearchReplaceDiffStrategy` works, see the [apply_diff documentation](/advanced-usage/available-tools/apply-diff#experimental-multi-file-edits-multi_file_apply_diff).
73+
74+
75+
---
76+
77+
## Best Practices
78+
79+
### When to Enable
80+
- Using capable AI models (Claude 3.5 Sonnet, GPT-4, etc.)
81+
- Comfortable reviewing multiple changes at once
82+
83+
### When to Keep Disabled
84+
- Working with less capable models that might struggle with complex multi-file contexts
85+
- Prefer reviewing each change individually
86+
87+
---
88+
89+
## Limitations
90+
91+
- **Experimental**: This feature is still being refined and may have edge cases
92+
- **Model dependent**: Works best with more capable AI models
93+
- **Token usage**: Initial requests may use more tokens due to larger context
94+
- **Complexity**: Very large batch operations might be harder to review
95+
96+
---
97+
98+
## Troubleshooting
99+
100+
### Changes Not Batching
101+
- Verify the experimental flag is enabled in settings
102+
- Check that your model supports multi-file operations
103+
- Ensure files aren't restricted by `.rooignore`
104+
105+
### Approval UI Not Appearing
106+
- Update to the latest version of Roo Code
107+
- Check VS Code's output panel for errors
108+
- Try disabling and re-enabling the feature
109+
110+
### Performance Issues
111+
- For very large batches, consider breaking the task into smaller chunks
112+
- Monitor token usage if working with limited API quotas
113+
114+
---
115+
116+
## See Also
117+
118+
- [`apply_diff` Tool Documentation](/advanced-usage/available-tools/apply-diff) - Detailed technical information
119+
- [Experimental Features](/features/experimental/experimental-features) - Other experimental capabilities
120+
- [`.rooignore` Configuration](/features/rooignore) - File access restrictions

‎docs/features/experimental/experimental-features.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ To enable or disable experimental features:
2121
The following experimental features are currently available:
2222

2323
- [Codebase Indexing](/features/experimental/codebase-indexing) - Semantic search through AI-powered codebase indexing
24+
- [Concurrent File Edits](/features/experimental/concurrent-file-edits) - Edit multiple files in a single operation
2425
- [Power Steering](/features/experimental/power-steering)
2526
- [Marketplace](/features/marketplace) - Discover and install modes and MCP servers to extend Roo Code
2627

0 commit comments

Comments
 (0)