128 lines
4.6 KiB
Markdown
128 lines
4.6 KiB
Markdown
|
|
# search_files
|
|
|
|
The `search_files` tool performs regex searches across multiple files in your project. It helps Roo locate specific code patterns, text, or other content throughout your codebase with contextual results.
|
|
|
|
## Parameters
|
|
|
|
The tool accepts these parameters:
|
|
|
|
- `path` (required): The path of the directory to search in, relative to the current working directory
|
|
- `regex` (required): The regular expression pattern to search for (uses Rust regex syntax)
|
|
- `file_pattern` (optional): Glob pattern to filter files (e.g., '*.ts' for TypeScript files)
|
|
|
|
## What It Does
|
|
|
|
This tool searches across files in a specified directory using regular expressions, showing each match with surrounding context. It's like having a powerful "Find in Files" feature that works across the entire project structure.
|
|
|
|
## When is it used?
|
|
|
|
- When Roo needs to find where specific functions or variables are used
|
|
- When Roo helps with refactoring and needs to understand usage patterns
|
|
- When Roo needs to locate all instances of a particular code pattern
|
|
- When Roo searches for text across multiple files with filtering capabilities
|
|
|
|
## Key Features
|
|
|
|
- Searches across multiple files in a single operation using high-performance Ripgrep
|
|
- Shows context around each match (1 line before and after)
|
|
- Filters files by type using glob patterns (e.g., only TypeScript files)
|
|
- Provides line numbers for easy reference
|
|
- Uses powerful regex patterns for precise searches
|
|
- Automatically limits output to 300 results with notification
|
|
- Truncates lines longer than 500 characters with "[truncated...]" marker
|
|
- Intelligently combines nearby matches into single blocks for readability
|
|
|
|
## Limitations
|
|
|
|
- Works best with text-based files (not effective for binary files like images)
|
|
- Performance may slow with extremely large codebases
|
|
- Uses Rust regex syntax, which may differ slightly from other regex implementations
|
|
- Cannot search within compressed files or archives
|
|
- Default context size is fixed (1 line before and after)
|
|
- May display varying context sizes when matches are close together due to result grouping
|
|
|
|
## How It Works
|
|
|
|
When the `search_files` tool is invoked, it follows this process:
|
|
|
|
1. **Parameter Validation**: Validates the required `path` and `regex` parameters
|
|
2. **Path Resolution**: Resolves the relative path to an absolute path
|
|
3. **Search Execution**:
|
|
- Uses Ripgrep (rg) for high-performance text searching
|
|
- Applies file pattern filtering if specified
|
|
- Collects matches with surrounding context
|
|
4. **Result Formatting**:
|
|
- Formats results with file paths, line numbers, and context
|
|
- Displays 1 line of context before and after each match
|
|
- Structures output for easy readability
|
|
- Limits results to a maximum of 300 matches with notification
|
|
- Truncates lines longer than 500 characters
|
|
- Merges nearby matches into contiguous blocks
|
|
|
|
## Search Results Format
|
|
|
|
The search results include:
|
|
|
|
- Relative file paths for each matching file (prefixed with #)
|
|
- Context lines before and after each match (1 line by default)
|
|
- Line numbers padded to 3 spaces followed by ` | ` and the line content
|
|
- A separator line (----) after each match group
|
|
|
|
Example output format:
|
|
```
|
|
# rel/path/to/app.ts
|
|
11 | // Some processing logic here
|
|
12 | // TODO: Implement error handling
|
|
13 | return processedData;
|
|
----
|
|
|
|
# Showing first 300 of 300+ results. Use a more specific search if necessary.
|
|
```
|
|
|
|
When matches occur close to each other, they're merged into a single block rather than shown as separate results:
|
|
|
|
```
|
|
# rel/path/to/auth.ts
|
|
13 | // Some code here
|
|
14 | // TODO: Add proper validation
|
|
15 | function validateUser(credentials) {
|
|
16 | // TODO: Implement rate limiting
|
|
17 | return checkDatabase(credentials);
|
|
----
|
|
```
|
|
|
|
## Examples When Used
|
|
|
|
- When asked to refactor a function, Roo first searches for all places the function is used to ensure comprehensive changes.
|
|
- When investigating bugs, Roo searches for similar patterns to identify related issues across the codebase.
|
|
- When addressing technical debt, Roo locates all TODO comments across the project.
|
|
- When analyzing dependencies, Roo finds all imports of a particular module.
|
|
|
|
## Usage Examples
|
|
|
|
Searching for TODO comments in all JavaScript files:
|
|
```
|
|
<search_files>
|
|
<path>src</path>
|
|
<regex>TODO|FIXME</regex>
|
|
<file_pattern>*.js</file_pattern>
|
|
</search_files>
|
|
```
|
|
|
|
Finding all usages of a specific function:
|
|
```
|
|
<search_files>
|
|
<path>.</path>
|
|
<regex>function\s+calculateTotal</regex>
|
|
<file_pattern>*.{js,ts}</file_pattern>
|
|
</search_files>
|
|
```
|
|
|
|
Searching for a specific import pattern across the entire project:
|
|
```
|
|
<search_files>
|
|
<path>.</path>
|
|
<regex>import\s+.*\s+from\s+['"]@components/</regex>
|
|
</search_files>
|
|
```
|