Using .codeassistantignore to manage file access in SourceCraft Code Assistant

.codeassistantignore is a file that manages the way Code Assistant works with your project files. It allows you to define files and directories that Code Assistant must not access or modify, similar to .gitignore for Git.

.codeassistantignore protects confidential information, prevents accidental changes to build artifacts or large files, and defines the Code Assistant scope in your workspace.

Create a file named .codeassistantignore in the root directory of your VS Code workspace. Add patterns to this file to tell Code Assistant which files and directories to ignore.

The .codeassistantignore file applies to both Code Assistant tools and context mentions, e.g., @directory.

Code Assistant continuously monitors .codeassistantignore. Any changes you make are uploaded automatically, ensuring Code Assistant always uses the most up-to-date rules. The .codeassistantignore file itself is always ignored by default, which prevents Code Assistant from changing its own access rules.

Pattern syntax

The .codeassistantignore syntax is identical to that of .gitignore. Here are some common examples:

• node_modules/: Ignores the entire node_modules directory.
• *.log: Ignores all files ending with .log.
• config/secrets.json: Ignores a specific file.
• !important.log: Exception. Code Assistant will not ignore this specific file, even if it matches a more general pattern, such as *.log.
• build/: Ignores the build directory.
• docs/**/*.md: Ignores all files with the .md extension in the docs directory or its subdirectories.

For a full syntax overview, see Git's .gitignore guide.

How Code Assistant tools work with .codeassistantignore

The .codeassistantignore rules apply to most Code Assistant tools.

Reading and writing with strict compliance

These tools directly check .codeassistantignore before any file operations. If a file is ignored, any of the following operations will be blocked:

• read_file: Ignored files will not be read.
• write_to_file: Ignored files will not be written or created.
• apply_diff: Quick edits will not apply to ignored files.
• insert_content: No writes will be made to ignored files.
• search_and_replace: Ignored files will be excluded from search and replace operations.
• list_code_definition_names: Ignored files will not be analyzed for code characters.

Detecting and listing files

• list_files and @directory inclusions: When Code Assistant is listing files or you are using @directory references, ignored files are either excluded or marked with 🔒. Both tools use the same filtering logic.
• Environment details: Information about your workspace, such as open tabs and project structure provided to Code Assistant are filtered to exclude or flag ignored items.

Context mentions

• @directory inclusions: Directory contents factors in .codeassistantignore patterns. Depending on the showCodeAssistantIgnoredFiles setting, ignored files are either filtered out or prefixed with [🔒].
• Mentions of specific files: Ignored files return File is ignored by .codeassistantignore settings rather than their contents.

Running commands

execute_command: This tool checks whether a command from a predefined list, such as cat or grep, targets an ignored file. If so, the command is blocked.

Main restrictions and scope

.codeassistantignore rules only apply to files and directories in the root directory of the VS Code workspace, leaving files elsewhere unaffected.

Protection for the execute_command tool is limited to a predefined list of file read commands. Custom scripts or less common utilities may go undetected.

.codeassistantignore effectively manages Code Assistant access to files via tools, without creating a system-level sandbox.

User experience and notifications

In file lists and @directory inclusions, files ignored by .codeassistantignore can be flagged with 🔒 depending on the showCodeAssistantIgnoredFiles setting (true by default).

Mentions of specific files return File is ignored by .codeassistantignore settings rather than their contents.

If a tool operation is blocked, Code Assistant gets this error: Access to <file_path> is denied by .codeassistantignore. file settings. Try to proceed without this file, or ask the user to update the .codeassistantignore file.

Typically, when an action is blocked by .codeassistantignore, the Code Assistant chat interface displays a relevant message.