Skip to main content

search_and_replace

The search_and_replace tool finds and replaces text within a file, supporting both literal strings and regular expression patterns. It allows for targeted replacements across multiple locations, optionally within specific line ranges.

Parameters​

Required Parameters​

  • path: The relative path (from the workspace saarthit) of the file to modify.
  • search: The text string or regex pattern to find.
  • replace: The text to replace matches with.

Optional Parameters​

  • start_line: The 1-based line number where the search scope begins.
  • end_line: The 1-based line number where the search scope ends (inclusive).
  • use_regex: Set to "true" to treat the search parameter as a regular expression pattern (default is false).
  • ignore_case: Set to "true" to perform a case-insensitive search (default is false).

What It Does​

This tool reads the specified file and performs a search-and-replace operation based on the provided parameters. It can operate on the entire file or be restricted to a specific range of lines. Changes are presented in a diff view for user review and approval before being saved.

When is it used?​

  • When renaming variables, functions, or classes across a file.
  • When updating specific text strings or values consistently.
  • When applying patterned changes using regular expressions.
  • When refactoring code requires replacing specific patterns.
  • When making targeted changes within a defined section of a file.

Key Features​

  • Flexible Searching: Supports both literal text and regular expression patterns.
  • Case Sensitivity Control: Option to ignore case during search.
  • Scoped Replacements: Can limit replacements to a specific range of lines (start_line, end_line).
  • Global Replacement: Performs replacements across the entire file (or specified range) by default.
  • Interactive Approval: Shows proposed changes in a diff view for user review and approval.
  • User Edit Support: Allows editing the proposed content directly within the diff view.
  • Context Tracking: Records the file edit operation.
  • Error Handling: Checks for missing parameters, file access issues, and invalid line numbers.

Limitations​

  • Single File Operation: Operates on only one file at a time. Use search_files to find patterns across multiple files first.
  • Review Overhead: The mandatory diff view approval adds an interactive step.
  • Regex Complexity: Complex regex patterns might require careful construction and testing.

How It Works​

When the search_and_replace tool is invoked, it follows this process:

  1. Parameter Validation: Checks for required path, search, replace, and validates optional parameters like line numbers and boolean flags.
  2. File Reading: Reads the content of the target file specified by path.
  3. Regex Construction:
    • If use_regex is false, the search string is escaped to treat it as literal text.
    • A RegExp object is created with the g (global) flag and optionally the i (ignore case) flag.
  4. Replacement Execution:
    • If start_line or end_line are provided, the file content is split into lines, the relevant section is isolated, the replacement is performed on that section, and the file content is reconstructed.
    • If no line range is specified, the replacement is performed on the entire file content string.
  5. Diff View Interaction:
    • Opens the file in the diff view showing original vs. proposed content.
    • Updates the diff view with the result of the replacement.
  6. User Approval: Presents the change via askApproval. Reverts if rejected.
  7. Saving Changes: If approved, saves the changes (including any user edits made in the diff view).
  8. File Context Tracking: Tracks the edit using cline.getFileContextTracker().trackFileContext.
  9. Result Reporting: Reports success (including user edits) or failure back to the AI model.

Usage Examples​

Simple text replacement throughout a file:

<search_and_replace>
<path>src/config.js</path>
<search>API_KEY_OLD</search>
<replace>API_KEY_NEW</replace>
</search_and_replace>

Case-insensitive regex replacement to update function calls:

<search_and_replace>
<path>src/app.ts</path>
<search>processData\((.*?)\)</search>
<replace>handleData($1)</replace>
<use_regex>true</use_regex>
<ignore_case>true</ignore_case>
</search_and_replace>

Replacing text only within lines 10 to 20:

<search_and_replace>
<path>README.md</path>
<search>Draft</search>
<replace>Final</replace>
<start_line>10</start_line>
<end_line>20</end_line>
</search_and_replace>