Performs exact string replacements in files within allowed directories.
Usage:
- You must use your Read tool at least once in the conversation before editing. This tool will error if you attempt an edit without reading the file.
- Paths can be relative to configured allowed directories, or absolute paths within allowed directories
- Paths outside allowed directories will be rejected
- When editing text from Read tool output, ensure you preserve the exact indentation (tabs/spaces) as it appears AFTER the line number prefix. The line number prefix format is "L{n}: ". Everything after that prefix is the actual file content to match. Never include any part of the line number prefix in `old_string` or `new_string`.
- ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.
- Only use emojis if the user explicitly requests it. Avoid adding emojis to files unless asked.
### Parameters
- `file_path`: Path to the file to modify - can be relative or absolute within allowed directories (required)
- `old_string`: Exact text to find and replace (required)
- `new_string`: Replacement text (required)
- `replace_all`: Replace all occurrences when true, default false (optional)
### Error Behavior
- The edit will FAIL if `old_string` is not found in the file with an error "oldString not found in content".
- The edit will FAIL if `old_string` is found multiple times in the file with an error "oldString found multiple times and requires more code context to uniquely identify the intended match". Either provide a larger string with more surrounding context to make it unique or use `replace_all` to change every instance of `old_string`.
### When to Use This Tool
- Making targeted changes to existing files
- Fixing bugs in specific code sections
- Updating function implementations
- Renaming variables across a file (with `replace_all: true`)
- Adding new code to existing files
### When NOT to Use This Tool
- Creating new files - use Write tool instead
- When most of a file needs to change - use Write tool instead
- When you haven't read the file yet - read it first!
### Examples
Replacing a single occurrence:
```
file_path: "src/main.rs"
old_string: "fn old_name() {"
new_string: "fn new_name() {"
```
Renaming a variable everywhere in a file:
```
file_path: "src/main.rs"
old_string: "old_var"
new_string: "new_var"
replace_all: true
```
Adding code after an existing line:
```
file_path: "src/main.rs"
old_string: "use std::io;"
new_string: "use std::io;\nuse std::fs;"
```
### Best Practices
1. Always read the file first using the Read tool
2. Copy the exact text from the Read output, preserving whitespace and indentation
3. Include enough context in `old_string` to make it unique
4. When adding new code, include the line before/after in `old_string` for context
5. Use `replace_all: true` when renaming variables or making consistent changes
6. Don't include line number prefixes (like "L42: ") in your old_string or new_string
7. Relative paths are resolved against allowed directories
### Common Mistakes to Avoid
- Forgetting to read the file first
- Including line number prefixes in old_string
- Not including enough context (causes "found multiple times" error)
- Changing indentation unintentionally
- Forgetting that old_string must match EXACTLY (including whitespace)