|
| 1 | +# append_to_file |
| 2 | + |
| 3 | +The `append_to_file` tool adds content to the end of a specified file. If the file doesn't exist, it creates the file with the provided content. It automatically handles directory creation if needed. |
| 4 | + |
| 5 | +## Parameters |
| 6 | + |
| 7 | +The tool accepts these parameters: |
| 8 | + |
| 9 | +- `path` (required): The relative path (from the workspace root) of the file to append to. |
| 10 | +- `content` (required): The content to append to the file. |
| 11 | + |
| 12 | +## What It Does |
| 13 | + |
| 14 | +This tool appends the provided `content` to the end of the file specified by `path`. If the target file doesn't exist, the tool creates it and populates it with the `content`. It also ensures any necessary parent directories for the file path are created. Changes are presented in a diff view for user approval before being saved. |
| 15 | + |
| 16 | +## When is it used? |
| 17 | + |
| 18 | +- When adding new entries to log files. |
| 19 | +- When appending data records to existing datasets (e.g., CSV, JSON lines). |
| 20 | +- When incrementally building a file where new content should always go at the end. |
| 21 | +- When creating a file for the first time with initial content, especially if subsequent operations will append to it. |
| 22 | + |
| 23 | +## Key Features |
| 24 | + |
| 25 | +- **Append or Create**: Appends content to existing files or creates new files if they don't exist. |
| 26 | +- **Interactive Approval**: Shows proposed changes (append or new file creation) in a diff view, requiring explicit user approval. |
| 27 | +- **User Edit Support**: Allows editing the proposed content directly within the diff view before final approval. |
| 28 | +- **Automatic Directory Creation**: Automatically creates parent directories if they don't exist for the specified `path`. |
| 29 | +- **Content Preprocessing**: Cleans content by removing potential AI model artifacts (like code fences) and unescaping HTML entities. |
| 30 | +- **Access Control**: Validates file access against `.rooignore` rules. |
| 31 | +- **Diff View Integration**: Opens the file in a diff view, scrolling to the first change for review. |
| 32 | +- **Partial Update Support**: Can handle streaming content (`block.partial`) into the diff view. |
| 33 | +- **Context Tracking**: Records the file edit operation for context management. |
| 34 | + |
| 35 | +## Limitations |
| 36 | + |
| 37 | +- **Append Only**: Content is always added to the *end* of the file; it cannot insert content at other positions. |
| 38 | +- **Review Overhead**: The mandatory diff view approval adds an interactive step. |
| 39 | +- **Potential for Large Files**: While generally efficient, appending large amounts of content repeatedly might impact performance less than `write_to_file` but more than `apply_diff` for targeted changes. |
| 40 | + |
| 41 | +## How It Works |
| 42 | + |
| 43 | +When the `append_to_file` tool is invoked, it follows this process: |
| 44 | + |
| 45 | +1. **Parameter Validation**: Checks for required `path` and `content`. Reports errors if missing. |
| 46 | +2. **Path Processing**: Resolves the relative `path` to an absolute path and checks if it's outside the workspace. |
| 47 | +3. **Access Control**: Validates file access against `.rooignore` rules using `rooIgnoreController`. |
| 48 | +4. **File Existence Check**: Determines if the file exists using `fileExistsAtPath`. |
| 49 | +5. **Content Preprocessing**: Removes markdown code fences, unescapes HTML entities (for non-Claude models), and strips potential line numbers. |
| 50 | +6. **Diff View Interaction**: |
| 51 | + * Opens the file in the diff view (`cline.diffViewProvider.open`). |
| 52 | + * If the file exists, prepares the `newContent` by prefixing it with the `originalContent` and a newline (`\n`). |
| 53 | + * Updates the diff view with the final content (`cline.diffViewProvider.update`), supporting partial (streaming) updates. |
| 54 | + * Scrolls to the first detected change after a complete update (`cline.diffViewProvider.scrollToFirstDiff`). |
| 55 | +7. **User Approval**: Presents the change (append or creation) via `askApproval`. Shows a formatted diff if appending. Reverts if rejected. |
| 56 | +8. **Saving Changes**: If approved, saves the changes using `cline.diffViewProvider.saveChanges`. |
| 57 | +9. **File Context Tracking**: Tracks the edit using `cline.getFileContextTracker().trackFileContext`. |
| 58 | +10. **Handling User Edits**: If the user edited the content in the diff view, reports the final merged content back to the AI. |
| 59 | +11. **Error Handling**: Uses the `handleError` callback for issues. Resets the diff view on completion, error, or rejection. |
| 60 | +12. **Result Reporting**: Reports success (including user edits) or failure back to the AI model using `pushToolResult`. |
| 61 | + |
| 62 | +## Usage Examples |
| 63 | + |
| 64 | +Appending log entries to an existing file: |
| 65 | + |
| 66 | +```xml |
| 67 | +<append_to_file> |
| 68 | +<path>logs/application.log</path> |
| 69 | +<content> |
| 70 | +[2024-04-18 10:30:00] INFO: User logged in successfully. |
| 71 | +[2024-04-18 10:30:05] WARN: Disk space running low. |
| 72 | +</content> |
| 73 | +</append_to_file> |
| 74 | +``` |
| 75 | + |
| 76 | +Creating a new file and adding initial content (if `notes.md` doesn't exist): |
| 77 | + |
| 78 | +```xml |
| 79 | +<append_to_file> |
| 80 | +<path>project/docs/notes.md</path> |
| 81 | +<content> |
| 82 | +# Project Notes |
| 83 | + |
| 84 | +- Initial setup complete. |
| 85 | +- Need to configure database connection. |
| 86 | +</content> |
| 87 | +</append_to_file> |
0 commit comments