---
metadata:
  - name: generator
    content: Diplodoc Platform v5.50.6
alternate:
  - https://sourcecraft.dev/portal/docs/en/code-assistant/operations/agent/codeassistantignore.md
  - https://sourcecraft.dev/portal/docs/ru/code-assistant/operations/agent/codeassistantignore.md
title: Using .codeassistantignore to manage file access in SourceCraft Code Assistant
description: How to use the .codeassistantignore file to manage access to SourceCraft Code Assistant files and project directories.
---
> **Documentation Index:** Fetch the complete configuration index at https://sourcecraft.dev/portal/docs/en/llms.txt


# Using .codeassistantignore to manage file access in SourceCraft Code Assistant

<!-- source: en/_includes/code-assistant/only-in-vscode.md -->
{% note warning %}

This feature is only available in Visual Studio Code.

{% endnote %}
<!-- endsource: en/_includes/code-assistant/only-in-vscode.md -->

`.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 {#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](https://git-scm.com/docs/gitignore).

### Exceptions {#excludes}

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:
>
> ```text
> 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:
>
> ```text
> # 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 {#how-it-works}

The `.codeassistantignore` rules apply to most Code Assistant tools.

### Reading and writing with strict compliance {#write-and-read}

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}

* `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 {#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}

`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 {#restrictions}

`.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 {#user-experience}

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.

#### Useful links {#see-also}

[Managing SourceCraft Code Assistant chat context in Visual Studio Code](https://sourcecraft.dev/portal/docs/en/code-assistant/operations/agent/context-mentions.md)