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.
• 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.

Exceptions

By default, Code Assistant ignores and does not add to context the files and folders listed in .codeassistantignore and .gitignore, unless they are explicitly referenced in the user's query.

In some cases, you may need to partially or fully unblock access to ignored files for Code Assistant. Do it by using the negation pattern ! in .codeassistantignore.

The negations specified in .codeassistantignore will apply both to .gitignore and .codeassistantignore itself.

For example, .gitignore is used to ignore the following folders and files:

generated/
vendor/
*.log

However, we want certain nested folders and files to remain accessible to Code Assistant, while excluding some in addition to what is specified in .gitignore. In this case, you can set up .codeassistantignore as follows:

# Hide a folder from Code Assistant in addition to what is specified in `.gitignore`
tests/integration/

# Expose one file from the hidden folder to Code Assistant
!tests/integration/readme.md

# Partially expose folders hidden by `.gitignore` to Code Assistant
!generated/api/
!vendor/internal/utils.go

# Expose one file out of all files matching the `.gitignore` pattern to Code Assistant
!important.log

# Expose all proto files to Code Assistant
!**/*.proto

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.

See also

Managing SourceCraft Code Assistant chat context in Visual Studio Code