MediaMetz/gemini-cli
1
0
Fork 0
mirror of https://github.com/google-gemini/gemini-cli.git synced 2026-03-10 14:10:37 -07:00
Code Issues Packages Projects Releases Wiki Activity

Docs: Refresh docs to organize and standardize reference materials. (#18403)

Browse Source
This commit is contained in:
Jenna Inouye
2026-02-13 14:09:17 -08:00
committed by GitHub
parent f76e24c00f
commit c7237f0c79
37 changed files with 2343 additions and 1676 deletions
Download Patch File Download Diff File Expand all files Collapse all files

172
docs/tools/file-system.md
View File

@@ -1,99 +1,49 @@
# Gemini CLI file system tools
# File system tools reference
The Gemini CLI provides a comprehensive suite of tools for interacting with the
local file system. These tools allow the Gemini model to read from, write to,
list, search, and modify files and directories, all under your control and
typically with confirmation for sensitive operations.
The 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.
**Note:** All file system tools operate within a `rootDirectory` (usually the
current working directory where you launched the CLI) for security. Paths that
you provide to these tools are generally expected to be absolute or are resolved
relative to this root directory.
## Technical reference
## 1. `list_directory` (ReadFolder)
All file system tools operate within a `rootDirectory` (the current working
directory or workspace root) for security.
`list_directory` lists the names of files and subdirectories directly within a
specified directory path. It can optionally ignore entries matching provided
glob patterns.
### `list_directory` (ReadFolder)
Lists the names of files and subdirectories directly within a specified path.
- **Tool name:** `list_directory`
- **Display name:** ReadFolder
- **File:** `ls.ts`
- **Parameters:**
- `path` (string, required): The absolute path to the directory to list.
- `ignore` (array of strings, optional): A list of glob patterns to exclude
from the listing (e.g., `["*.log", ".git"]`).
- `respect_git_ignore` (boolean, optional): Whether to respect `.gitignore`
patterns when listing files. Defaults to `true`.
- **Behavior:**
- Returns a list of file and directory names.
- Indicates whether each entry is a directory.
- Sorts entries with directories first, then alphabetically.
- **Output (`llmContent`):** A string like:
`Directory listing for /path/to/your/folder:\n[DIR] subfolder1\nfile1.txt\nfile2.png`
- **Confirmation:** No.
- **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.
## 2. `read_file` (ReadFile)
### `read_file` (ReadFile)
`read_file` reads and returns the content of a specified file. This tool handles
text, images (PNG, JPG, GIF, WEBP, SVG, BMP), audio files (MP3, WAV, AIFF, AAC,
OGG, FLAC), and PDF files. For text files, it can read specific line ranges.
Other binary file types are generally skipped.
Reads and returns the content of a specific file. Supports text, images, audio,
and PDF.
- **Tool name:** `read_file`
- **Display name:** ReadFile
- **File:** `read-file.ts`
- **Parameters:**
- `path` (string, required): The absolute path to the file to read.
- `offset` (number, optional): For text files, the 0-based line number to
start reading from. Requires `limit` to be set.
- `limit` (number, optional): For text files, the maximum number of lines to
read. If omitted, reads a default maximum (e.g., 2000 lines) or the entire
file if feasible.
- **Behavior:**
- For text files: Returns the content. If `offset` and `limit` are used,
returns only that slice of lines. Indicates if content was truncated due to
line limits or line length limits.
- For image, audio, and PDF files: Returns the file content as a
base64-encoded data structure suitable for model consumption.
- For other binary files: Attempts to identify and skip them, returning a
message indicating it's a generic binary file.
- **Output:** (`llmContent`):
- For text files: The file content, potentially prefixed with a truncation
message (e.g.,
`[File content truncated: showing lines 1-100 of 500 total lines...]\nActual file content...`).
- For image/audio/PDF files: An object containing `inlineData` with `mimeType`
and base64 `data` (e.g.,
`{ inlineData: { mimeType: 'image/png', data: 'base64encodedstring' } }`).
- For other binary files: A message like
`Cannot display content of binary file: /path/to/data.bin`.
- **Confirmation:** No.
- **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.
## 3. `write_file` (WriteFile)
### `write_file` (WriteFile)
`write_file` writes content to a specified file. If the file exists, it will be
overwritten. If the file doesn't exist, it (and any necessary parent
directories) will be created.
Writes content to a specified file, overwriting it if it exists or creating it
if not.
- **Tool name:** `write_file`
- **Display name:** WriteFile
- **File:** `write-file.ts`
- **Parameters:**
- `file_path` (string, required): The absolute path to the file to write to.
- `content` (string, required): The content to write into the file.
- **Behavior:**
- Writes the provided `content` to the `file_path`.
- Creates parent directories if they don't exist.
- **Output (`llmContent`):** A success message, e.g.,
`Successfully overwrote file: /path/to/your/file.txt` or
`Successfully created and wrote to new file: /path/to/new/file.txt`.
- **Confirmation:** Yes. Shows a diff of changes and asks for user approval
before writing.
- **Arguments:**
- `file_path` (string, required): Path to the file.
- `content` (string, required): Data to write.
- **Confirmation:** Requires manual user approval.
## 4. `glob` (FindFiles)
### `glob` (FindFiles)
`glob` finds files matching specific glob patterns (e.g., `src/**/*.ts`,
`*.md`), returning absolute paths sorted by modification time (newest first).
Finds files matching specific glob patterns across the workspace.
- **Tool name:** `glob`
- **Display name:** FindFiles
@@ -161,56 +111,16 @@ 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`
- **Display name:** Edit
- **File:** `edit.ts`
- **Parameters:**
- `file_path` (string, required): The absolute path to the file to modify.
- `old_string` (string, required): The exact literal text to 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.
- **Confirmation:** Requires manual user approval.
**CRITICAL:** This string must uniquely identify the single instance to
change. It should include at least 3 lines of context _before_ and _after_
the target text, matching whitespace and indentation precisely. If
`old_string` is empty, the tool attempts to create a new file at `file_path`
with `new_string` as content.
## Next steps
- `new_string` (string, required): The exact literal text to replace
`old_string` with.
- `expected_replacements` (number, optional): The number of occurrences to
replace. Defaults to `1`.
- **Behavior:**
- If `old_string` is empty and `file_path` does not exist, creates a new file
with `new_string` as content.
- If `old_string` is provided, it reads the `file_path` and attempts to find
exactly one occurrence of `old_string`.
- If one occurrence is found, it replaces it with `new_string`.
- **Enhanced reliability (multi-stage edit correction):** To significantly
improve the success rate of edits, especially when the model-provided
`old_string` might not be perfectly precise, the tool incorporates a
multi-stage edit correction mechanism.
- If the initial `old_string` isn't found or matches multiple locations, the
tool can leverage the Gemini model to iteratively refine `old_string` (and
potentially `new_string`).
- This self-correction process attempts to identify the unique segment the
model intended to modify, making the `replace` operation more robust even
with slightly imperfect initial context.
- **Failure conditions:** Despite the correction mechanism, the tool will fail
if:
- `file_path` is not absolute or is outside the root directory.
- `old_string` is not empty, but the `file_path` does not exist.
- `old_string` is empty, but the `file_path` already exists.
- `old_string` is not found in the file after attempts to correct it.
- `old_string` is found multiple times, and the self-correction mechanism
cannot resolve it to a single, unambiguous match.
- **Output (`llmContent`):**
- On success:
`Successfully modified file: /path/to/file.txt (1 replacements).` or
`Created new file: /path/to/new_file.txt with provided content.`
- On failure: An error message explaining the reason (e.g.,
`Failed to edit, 0 occurrences found...`,
`Failed to edit, expected 1 occurrences but found 2...`).
- **Confirmation:** Yes. Shows a diff of the proposed changes and asks for user
approval before writing to the file.
These file system tools provide a foundation for the Gemini CLI to understand
and interact with your local project context.
- 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.