> ## Documentation Index
> Fetch the complete documentation index at: https://chatcli.edilsonfreitas.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Filtering with .chatignore

> Control which files and directories are sent as context to the AI using .gitignore-style rules.

ChatCLI supports a file exclusion system inspired by `.gitignore`. This allows you to refine the context sent to the AI, avoiding irrelevant files such as tests, logs, dependencies, and builds.

## Why filter files?

| Benefit             | Description                                                             |
| ------------------- | ----------------------------------------------------------------------- |
| **Focus**           | Sends only relevant source code, resulting in more accurate responses   |
| **Efficiency**      | Saves tokens, which reduces costs on paid APIs                          |
| **Speed**           | Processes large projects faster by ignoring unnecessary files           |
| **Noise reduction** | Avoids polluting the context with compiled files, dependencies, or logs |

***

## The `.chatignore` file

The syntax is **identical** to `.gitignore`:

* Lines starting with `#` are comments
* To ignore an entire directory, add the name followed by `/` (e.g., `docs/`)
* Use glob patterns (wildcards) to ignore files (e.g., `*_test.go`, `*.log`)

### Practical example

```gitignore theme={"system"}
# Ignore all Go test files
*_test.go

# Ignore entire directories
docs/
e2e/
vendor/
node_modules/
dist/
build/

# Ignore CI configuration files and logs
.github/
golangci.yml
*.log

# Ignore binaries and compiled files
*.exe
*.so
*.dylib
```

***

## Precedence hierarchy

ChatCLI searches for an ignore file in a specific order. The **first one found** is used and the rest are ignored:

| Priority    | Location                                | Description                          |
| ----------- | --------------------------------------- | ------------------------------------ |
| 1 (highest) | `CHATCLI_IGNORE` variable               | Absolute path to a rules file        |
| 2           | `.chatignore` in the analyzed directory | Project-specific rules               |
| 3           | `~/.chatcli/.chatignore`                | User's global rules                  |
| 4 (lowest)  | Built-in default rules                  | Ignores `.git`, `node_modules`, etc. |

### Example with environment variable

```bash theme={"system"}
export CHATCLI_IGNORE="~/configs/meu_ignore_global.txt"
```

<Warning>
  **Rules are not merged.** Only the first ignore file found in the hierarchy is used. If you set `CHATCLI_IGNORE`, the project and global directory `.chatignore` files will be ignored.
</Warning>

***

## Default rules

When no `.chatignore` file is found, ChatCLI uses built-in rules that already automatically ignore:

* `.git/`
* `node_modules/`
* `vendor/`
* `__pycache__/`
* `.idea/`, `.vscode/`
* Binary and compiled files

***

## Usage tips

* Create a `.chatignore` at the **root of each project** for specific rules
* Use the global `~/.chatcli/.chatignore` for universal rules (e.g., `.DS_Store`, `Thumbs.db`)
* Combine with `@file --mode smart` so the AI selects only the most relevant files within the already filtered scope