From e9421e59fcd26208d59beef3b37350ae277d1740 Mon Sep 17 00:00:00 2001 From: hannesrudolph Date: Fri, 16 May 2025 01:21:48 -0600 Subject: [PATCH] feat: Add .rooignore feature documentation and sidebar entry --- docs/features/rooignore.md | 69 ++++++++++++++++++++++++++++++++++++++ sidebars.ts | 1 + 2 files changed, 70 insertions(+) create mode 100644 docs/features/rooignore.md diff --git a/docs/features/rooignore.md b/docs/features/rooignore.md new file mode 100644 index 00000000..8f1ba8ea --- /dev/null +++ b/docs/features/rooignore.md @@ -0,0 +1,69 @@ +--- +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. \ No newline at end of file diff --git a/sidebars.ts b/sidebars.ts index 7ff469bd..01c69ae4 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -35,6 +35,7 @@ const sidebars: SidebarsConfig = { 'features/footgun-prompting', 'features/keyboard-shortcuts', 'features/model-temperature', + 'features/rooignore', 'features/settings-management', 'features/shell-integration', 'features/suggested-responses',