File size: 5,151 Bytes
7a1ad33 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 | # File system tools reference
Gemini CLI core provides a suite of tools for interacting with the local file
system. These tools allow the model to explore and modify your codebase.
## Technical reference
All file system tools operate within a `rootDirectory` (the current working
directory or workspace root) for security.
### `list_directory` (ReadFolder)
Lists the names of files and subdirectories directly within a specified path.
- **Tool name:** `list_directory`
- **Arguments:**
- `dir_path` (string, required): Absolute or relative path to the directory.
- `ignore` (array, optional): Glob patterns to exclude.
- `file_filtering_options` (object, optional): Configuration for `.gitignore`
and `.geminiignore` compliance.
### `read_file` (ReadFile)
Reads and returns the content of a specific file. Supports text, images, audio,
and PDF.
- **Tool name:** `read_file`
- **Arguments:**
- `file_path` (string, required): Path to the file.
- `offset` (number, optional): Start line for text files (0-based).
- `limit` (number, optional): Maximum lines to read.
### `write_file` (WriteFile)
Writes content to a specified file, overwriting it if it exists or creating it
if not.
- **Tool name:** `write_file`
- **Arguments:**
- `file_path` (string, required): Path to the file.
- `content` (string, required): Data to write.
- **Confirmation:** Requires manual user approval.
### `glob` (FindFiles)
Finds files matching specific glob patterns across the workspace.
- **Tool name:** `glob`
- **Display name:** FindFiles
- **File:** `glob.ts`
- **Parameters:**
- `pattern` (string, required): The glob pattern to match against (for
example, `"*.py"`, `"src/**/*.js"`).
- `path` (string, optional): The absolute path to the directory to search
within. If omitted, searches the tool's root directory.
- `case_sensitive` (boolean, optional): Whether the search should be
case-sensitive. Defaults to `false`.
- `respect_git_ignore` (boolean, optional): Whether to respect .gitignore
patterns when finding files. Defaults to `true`.
- **Behavior:**
- Searches for files matching the glob pattern within the specified directory.
- Returns a list of absolute paths, sorted with the most recently modified
files first.
- Ignores common nuisance directories like `node_modules` and `.git` by
default.
- **Output (`llmContent`):** A message like:
`Found 5 file(s) matching "*.ts" within src, sorted by modification time (newest first):\nsrc/file1.ts\nsrc/subdir/file2.ts...`
- **Confirmation:** No.
### `grep_search` (SearchText)
`grep_search` searches for a regular expression pattern within the content of
files in a specified directory. Can filter files by a glob pattern. Returns the
lines containing matches, along with their file paths and line numbers.
- **Tool name:** `grep_search`
- **Display name:** SearchText
- **File:** `grep.ts`
- **Parameters:**
- `pattern` (string, required): The regular expression (regex) to search for
(for example, `"function\s+myFunction"`).
- `path` (string, optional): The absolute path to the directory to search
within. Defaults to the current working directory.
- `include` (string, optional): A glob pattern to filter which files are
searched (for example, `"*.js"`, `"src/**/*.{ts,tsx}"`). If omitted,
searches most files (respecting common ignores).
- **Behavior:**
- Uses `git grep` if available in a Git repository for speed; otherwise, falls
back to system `grep` or a JavaScript-based search.
- Returns a list of matching lines, each prefixed with its file path (relative
to the search directory) and line number.
- **Output (`llmContent`):** A formatted string of matches, for example:
```
Found 3 matches for pattern "myFunction" in path "." (filter: "*.ts"):
---
File: src/utils.ts
L15: export function myFunction() {
L22: myFunction.call();
---
File: src/index.ts
L5: import { myFunction } from './utils';
---
```
- **Confirmation:** No.
### `replace` (Edit)
`replace` replaces text within a file. By default, the tool expects to find and
replace exactly ONE occurrence of `old_string`. If you want to replace multiple
occurrences of the exact same string, set `allow_multiple` to `true`. This tool
is designed for precise, targeted changes and requires significant context
around the `old_string` to ensure it modifies the correct location.
- **Tool name:** `replace`
- **Arguments:**
- `file_path` (string, required): Path to the file.
- `instruction` (string, required): Semantic description of the change.
- `old_string` (string, required): Exact literal text to find.
- `new_string` (string, required): Exact literal text to replace with.
- `allow_multiple` (boolean, optional): If `true`, replaces all occurrences.
If `false` (default), only succeeds if exactly one occurrence is found.
- **Confirmation:** Requires manual user approval.
## Next steps
- Follow the [File management tutorial](../cli/tutorials/file-management.md) for
practical examples.
- Learn about [Trusted folders](../cli/trusted-folders.md) to manage access
permissions.
|