69 lines
No EOL
5 KiB
Markdown
69 lines
No EOL
5 KiB
Markdown
---
|
|
sidebar_label: .rooignore
|
|
---
|
|
|
|
# Using .rooignore to Control File Access
|
|
|
|
The `.rooignore` file is a key feature for managing Roo Code's interaction with your project files. It allows you to specify files and directories that Roo should not access or modify, similar to how `.gitignore` works for Git.
|
|
|
|
## What is `.rooignore`?
|
|
|
|
* **Purpose**: To protect sensitive information, prevent accidental changes to build artifacts or large assets, and generally define Roo's operational scope within your workspace.
|
|
* **How to Use**: Create a file named `.rooignore` in the root directory of your VS Code workspace. List patterns in this file to tell Roo which files and directories to ignore.
|
|
|
|
Roo actively monitors the `.rooignore` file. Any changes you make are reloaded automatically, ensuring Roo always uses the most current rules. The `.rooignore` file itself is always implicitly ignored, so Roo cannot change its own access rules.
|
|
|
|
## Pattern Syntax
|
|
|
|
The syntax for `.rooignore` is identical to `.gitignore`. Here are common examples:
|
|
|
|
* `node_modules/`: Ignores the entire `node_modules` directory.
|
|
* `*.log`: Ignores all files ending in `.log`.
|
|
* `config/secrets.json`: Ignores a specific file.
|
|
* `!important.log`: An exception; Roo will *not* ignore this specific file, even if a broader pattern like `*.log` exists.
|
|
* `build/`: Ignores the `build` directory.
|
|
* `docs/**/*.md`: Ignores all Markdown files in the `docs` directory and its subdirectories.
|
|
|
|
For a comprehensive guide on syntax, refer to the [official Git documentation on .gitignore](https://git-scm.com/docs/gitignore).
|
|
|
|
## How Roo Tools Interact with `.rooignore`
|
|
|
|
`.rooignore` rules are enforced across various Roo tools:
|
|
|
|
### Strict Enforcement (Reads & Writes)
|
|
|
|
These tools directly check `.rooignore` before any file operation. If a file is ignored, the operation is blocked:
|
|
|
|
* [`read_file`](/advanced-usage/available-tools/read-file): Will not read ignored files.
|
|
* [`write_to_file`](/advanced-usage/available-tools/write-to-file): Will not write to or create new ignored files.
|
|
* [`apply_diff`](/advanced-usage/available-tools/apply-diff): Will not apply diffs to ignored files.
|
|
* [`list_code_definition_names`](/advanced-usage/available-tools/list-code-definition-names): Will not parse ignored files for code symbols.
|
|
|
|
### File Editing Tools (Potential Write Bypass)
|
|
|
|
The [`insert_content`](/advanced-usage/available-tools/insert-content) and [`search_and_replace`](/advanced-usage/available-tools/search-and-replace) tools use an internal component for managing changes.
|
|
**Important**: Currently, the final write operation performed by these tools might bypass `.rooignore` rules. While initial read attempts might be blocked, the save action itself does not have an explicit check.
|
|
|
|
### File Discovery and Listing
|
|
|
|
* **[`list_files`](/advanced-usage/available-tools/list-files) Tool**: When Roo lists files, ignored files are typically omitted or marked with a 🔒 symbol (see "User Experience" below).
|
|
* **Environment Details**: Information about your workspace (like open tabs and project structure) provided to Roo is filtered to exclude or mark ignored items.
|
|
|
|
### Command Execution
|
|
|
|
* **[`execute_command`](/advanced-usage/available-tools/execute-command) Tool**: This tool checks if a command (from a predefined list like `cat` or `grep`) targets an ignored file. If so, execution is blocked.
|
|
|
|
## Key Limitations and Scope
|
|
|
|
* **Workspace-Centric**: `.rooignore` rules apply **only to files and directories within the current VS Code workspace root**. Files outside this scope are not affected.
|
|
* **[`execute_command`](/advanced-usage/available-tools/execute-command) Specificity**: Protection for `execute_command` is limited to a predefined list of file-reading commands. Custom scripts or uncommon utilities might not be caught.
|
|
* **Write Operations via [`insert_content`](/advanced-usage/available-tools/insert-content) & [`search_and_replace`](/advanced-usage/available-tools/search-and-replace)**: As noted, these tools might be able to write to ignored files due to current limitations in their save mechanism.
|
|
* **Not a Full Sandbox**: `.rooignore` is a powerful tool for controlling Roo's file access via its tools, but it does not create a system-level sandbox.
|
|
|
|
## User Experience and Notifications
|
|
|
|
* **Visual Cue (🔒)**: In file listings, files ignored by `.rooignore` may be marked with a lock symbol (🔒), depending on the `showRooIgnoredFiles` setting (defaults to `true`).
|
|
* **Error Messages**: If a tool operation is blocked, Roo receives an error: `"Access to [file_path] is blocked by the .rooignore file settings. You must try to continue in the task without using this file, or ask the user to update the .rooignore file."`
|
|
* **Chat Notifications**: You will typically see a notification in the Roo chat interface when an action is blocked due to `.rooignore`.
|
|
|
|
This guide helps you understand the `.rooignore` feature, its capabilities, and its current limitations, so you can effectively manage Roo's interaction with your codebase. |