A gitignored generated client is invisible to Cursor's Agent — how does .cursorignore re-include it, and when does a ! negation fail?
answer
- Git's pattern syntax, not new
- a bang overrides the defaults
- negate the directory, not the file
- excluded folders are never traversed
- parent-folder search is a setting
basics
~20 sAdd a ! pattern for the directory to .cursorignore, such as !src/generated/, which overrides .gitignore and the default list. Negating a single file fails when a parent directory is excluded, because excluded directories are not traversed.
solid answer
~40 s`.cursorignore` lives in the project root and uses `.gitignore` syntax (`*`, `**`, `?`, `!`, `#` comments). Cursor ignores gitignored and default-listed files automatically, and a `!` line in `.cursorignore` overrides that, so `!src/generated/` brings a gitignored generated client back without making Git track it. The trap is Git's nested-path rule: you cannot re-include a file if a parent directory is excluded, because excluded directories are not traversed. `!src/generated/client.ts` alone therefore does nothing; negate the directory, or follow the reference's workaround of excluding the nested directory's contents and then negating the file. For monorepos opened one package at a time, the **Hierarchical Cursor Ignore** setting makes Cursor look for `.cursorignore` files in parent directories.
go deeper
Recall that .cursorignore uses Git's ignore syntax and that a ! line re-includes something that would otherwise be ignored.
Explain why negating a file inside an excluded directory has no effect, and how negating the directory or targeting its contents fixes it.
Keep generated code gitignored yet visible to Agent, test patterns with git check-ignore, and enable Hierarchical Cursor Ignore where people open monorepo packages.
Weigh what Agent should see against noise and exposure; re-including large generated trees helps accuracy but widens what Agent can read into requests.
## The situation Generated code is usually gitignored: an API client generated from an OpenAPI spec under `src/generated/`, a `dist/` bundle. Cursor treats `.gitignore` entries as ignored for its AI features, so Agent cannot read the client it is supposed to call and writes code against guessed signatures. Deleting the `.gitignore` entry would let Git pick up generated files; the fix belongs in `.cursorignore`. Before writing a pattern, know every source that can hide a file from Agent, Tab, Inline Edit and @-mention references: - the repository's `.gitignore`, honoured automatically; - Cursor's built-in default ignore list, which includes lock files, `.env*`, binaries, documents such as `*.csv` and `*.pdf`, and folders such as `node_modules/` and `.next/`; - global ignore patterns in your user settings, empty by default; - the project's own `.cursorignore`; - `.cursorignore` files in parent directories, when Hierarchical Cursor Ignore is enabled. ## .cursorignore syntax `.cursorignore` sits in the project root and uses `.gitignore` syntax: | Pattern | Meaning | |---|---| | `*` | Any characters except `/` | | `**` | Any characters including `/` | | `?` | A single character | | `!` | Negates a pattern, un-ignoring a previously ignored path | | `#` at the start of a line | A comment | | Trailing spaces | Ignored unless escaped with `\` | Typical lines from Cursor's reference: `config.json` (one file), `dist/` (a directory), `*.log` (an extension), `**/logs` (nested directories) and `!app/` (re-include a directory). ## Re-including what .gitignore or the defaults hid Cursor's reference states that files in `.gitignore` and on the default ignore list are ignored automatically, and that you override them with a `!` prefix in `.cursorignore`. For a gitignored `src/generated/` directory: ```bash # .cursorignore !src/generated/ ``` The same mechanism brings back a default exclusion, such as `.env.example` (hidden by `.env*`) or a `*.csv` test fixture. ## When a ! pattern fails Negation follows Git's rule for nested paths: **you cannot re-include a file if a parent directory is excluded**. Excluded directories are not traversed, so patterns on the files inside them have no effect. The reference's example: ```bash public/* # works: the file sits at the top level !public/index.html # no effect: its parent public/assets is excluded !public/assets/style.css ``` The reference's workaround targets the nested directory's contents rather than the directory itself: ```bash public/assets/* !public/assets/style.css ``` Applied to the generated client: `!src/generated/client.ts` alone does nothing while `src/generated/` is excluded as a directory. Negate the directory, as above, or restructure the patterns so the parent is never excluded. ## A short procedure 1. Find which source hides the file: `.gitignore`, the default list or `.cursorignore` itself. 2. Add a `!` line for the highest excluded directory on the file's path, not only for the file. 3. Test the pattern; the reference suggests `git check-ignore -v <file>`, which prints the matching pattern, since the syntax is Git's. ## Monorepos: Hierarchical Cursor Ignore Developers often open one package of a monorepo rather than the whole repository, while the ignore file lives at the repository root. The setting **Hierarchical Cursor Ignore** (Cursor Settings > Indexing > Ignore Files) makes Cursor search parent directories for `.cursorignore` files, so the root file still applies. ## How much to re-include Re-including is a trade, not a free win: - **Accuracy.** An Agent that can read the generated client's types writes calls that match them. - **Noise.** Large generated trees fill search results and context, which is one of the reasons Cursor ignores generated and third-party code by default. - **Exposure.** Whatever Agent can open can be included in a model request, so re-include the directory Agent needs, not a broad pattern such as `!**/*`. ## Common mistakes - Negating a single file inside a directory that is excluded as a whole. - Deleting the `.gitignore` entry so Agent can see generated code, which makes Git track it. - Expecting a `.cursorignore` in a parent folder to apply without Hierarchical Cursor Ignore. - Writing `#` before a pattern to "enable" it; `#` starts a comment.
- How do you check which pattern is hiding a file from Cursor's Agent?Cursor's ignore-file reference suggests `git check-ignore -v <file>`, which prints the source and pattern that matched, since `.cursorignore` uses Git's syntax. Check `.gitignore` and the default list as well, because either can be the hiding source rather than `.cursorignore`.
- A developer opens only packages/api of a monorepo whose .cursorignore sits at the repository root. Does it apply?Only if Hierarchical Cursor Ignore is enabled (Cursor Settings > Indexing > Ignore Files). That setting makes Cursor search parent directories for `.cursorignore` files; the reference otherwise describes the file in the root of the folder you open.
- You must delete the .gitignore entry before Cursor's Agent can read the file.
- A later ! line always overrides earlier patterns, whatever the directory.
- .cursorignore uses its own syntax rather than Git's ignore patterns.
- Gitignored and default-ignored files cannot be re-included for Agent.