diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/cli/configuration.md | 2 | ||||
| -rw-r--r-- | docs/core/tools-api.md | 1 | ||||
| -rw-r--r-- | docs/index.md | 2 | ||||
| -rw-r--r-- | docs/tools/file-system.md | 30 | ||||
| -rw-r--r-- | docs/tools/index.md | 2 |
5 files changed, 23 insertions, 14 deletions
diff --git a/docs/cli/configuration.md b/docs/cli/configuration.md index 22d4f698..703cf2c4 100644 --- a/docs/cli/configuration.md +++ b/docs/cli/configuration.md @@ -70,7 +70,7 @@ When you create a `.gemini/settings.json` file for project-specific settings, or - **Default:** `false` (users will be prompted for most tool calls). - **Behavior:** - If set to `true`, the CLI will bypass the confirmation prompt for tools deemed safe. An indicator may be shown in the UI when auto-accept is active. - - Potentially destructive or system-modifying tools (like `execute_bash_command` or `edit_file`) will likely still require confirmation regardless of this setting. + - Potentially destructive or system-modifying tools (like `execute_bash_command` or `write_file`) will likely still require confirmation regardless of this setting. - **Example:** `"autoAccept": true` - **`theme`** (string): diff --git a/docs/core/tools-api.md b/docs/core/tools-api.md index 8bfd55aa..92a09661 100644 --- a/docs/core/tools-api.md +++ b/docs/core/tools-api.md @@ -35,6 +35,7 @@ The core comes with a suite of pre-defined tools, typically found in `packages/c - **File System Tools:** - `LSTool` (`ls.ts`): Lists directory contents. - `ReadFileTool` (`read-file.ts`): Reads the content of a single file. + - `WriteFileTool` (`write-file.ts`): Writes content to a file. - `GrepTool` (`grep.ts`): Searches for patterns in files. - `GlobTool` (`glob.ts`): Finds files matching glob patterns. - `EditTool` (`edit.ts`): Performs in-place modifications to files (often requiring confirmation). diff --git a/docs/index.md b/docs/index.md index e62a4592..ea0c31b4 100644 --- a/docs/index.md +++ b/docs/index.md @@ -25,7 +25,7 @@ This documentation is organized into the following sections: - **[Tools API](./core/tools-api.md):** Information on how the core manages and exposes tools. - **Tools:** - **[Tools Overview](./tools/index.md):** A general look at the available tools. - - **[File System Tools](./tools/file-system.md):** Documentation for tools like `read_file`, `edit_file`, etc. + - **[File System Tools](./tools/file-system.md):** Documentation for tools like `read_file`, `write_file`, etc. - **[Shell Tool](./tools/shell.md):** Using the `execute_bash_command` tool. - **[Web Fetch Tool](./tools/web-fetch.md):** Using the `web_fetch` tool. - **[Web Search Tool](./tools/web-search.md):** Using the `google_web_search` tool. diff --git a/docs/tools/file-system.md b/docs/tools/file-system.md index 585db0f8..655611a3 100644 --- a/docs/tools/file-system.md +++ b/docs/tools/file-system.md @@ -53,7 +53,6 @@ All file system tools operate within a `rootDirectory` (usually the current work - **Behavior:** - Writes the provided `content` to the `file_path`. - Creates parent directories if they don't exist. - - **Self-correction:** Before writing, the tool may use the Gemini model to correct the provided content to ensure it is valid and well-formed. - **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. @@ -102,24 +101,33 @@ All file system tools operate within a `rootDirectory` (usually the current work ``` - **Confirmation:** No. -## 6. `edit_file` (EditFile) +## 6. `replace` (Edit) -- **Tool Name:** `edit_file` -- **Display Name:** EditFile +- **Tool Name:** `replace` +- **Display Name:** Edit - **File:** `edit.ts` -- **Description:** Replaces text within a file. By default, replaces a single occurrence, but can replace multiple occurrences when `expected_replacements` is specified. This tool is designed for precise, targeted changes and requires significant context around the `old_string` to ensure it modifies the correct location. It can also be used to create new files if `old_string` is empty and the `file_path` does not exist. +- **Description:** Replaces text within a file. By default, replaces a single occurrence, but can replace multiple occurrences when `expected_replacements` is specified. This tool is designed for precise, targeted changes and requires significant context around the `old_string` to ensure it modifies the correct location. - **Parameters:** - `file_path` (string, required): The absolute path to the file to modify. - `old_string` (string, required): The exact literal text to replace. **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. - `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:** - - **Modifying existing files**: Replaces exact text matches. File must exist unless the first edit has an empty `old_string` (indicating file creation). - - **Creating new files**: Use an empty `old_string` in the first edit to create a new file with `new_string` as the content. - - **Batch editing**: Applies multiple changes in sequence to the same file. - - **Enhanced Reliability**: Incorporates multi-stage edit correction to improve success rates when initial text matches aren't perfect. - - **Context Requirements**: Each `old_string` must uniquely identify the target location with sufficient context (typically 3+ lines before and after). -- **Output (`llmContent`):** Reports number of edits applied, attempted, and any failures with specific error details for troubleshooting. + - 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 from the AI. + - **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 robust foundation for the Gemini CLI to understand and interact with your local project context. diff --git a/docs/tools/index.md b/docs/tools/index.md index 614dc16a..2e3b7c26 100644 --- a/docs/tools/index.md +++ b/docs/tools/index.md @@ -30,7 +30,7 @@ You will typically see messages in the CLI indicating when a tool is being calle ## Security and Confirmation -Many tools, especially those that can modify your file system or execute commands (`edit_file`, `execute_bash_command`), are designed with safety in mind. The Gemini CLI will typically: +Many tools, especially those that can modify your file system or execute commands (`write_file`, `edit`, `execute_bash_command`), are designed with safety in mind. The Gemini CLI will typically: - **Require Confirmation:** Prompt you before executing potentially sensitive operations, showing you what action is about to be taken. - **Utilize Sandboxing:** All tools are subject to restrictions enforced by sandboxing (see [README](../../README.md#sandboxing)). |