skip to content

Before anyone writes a .cursorignore, which files does Cursor already keep away from Agent and Tab, and where do cross-project ignore patterns go?

level: juniorimportance: should knowfreq 7%

answer

  1. three sources before you start
  2. Git's own ignore file counts
  3. lock files, env files, VCS folders
  4. keys and credentials not covered
  5. user-settings list starts empty

basics

~20 s

Cursor already ignores everything in .gitignore plus a built-in default list: .env* files, .git/, lock files, binaries, media, archives and folders like node_modules/. Global ignore patterns in user settings cover every project, but that list starts empty.

solid answer

~40 s

Cursor blocks ignored files from Agent, Tab, Inline Edit and @-mention references. Without any `.cursorignore`, three sources apply: your `.gitignore`; Cursor's **default ignore list** (lock files such as `package-lock.json`, `yarn.lock` and `*.lock`, `.env*`, `.git/`, binaries, documents, media, archives, and folders like `node_modules/` and `.venv/`); and **global ignore patterns** in user settings, which apply to all projects but are empty by default. Keys and credential files such as `*.pem` or `credentials.json` are not on the default list and the global list starts empty, so unless `.gitignore` covers them they stay readable until someone adds them. A `.cursorignore` in the project root adds more, and a `!` line there re-includes something a default hid.

go deeper

for a junior

Remember three sources work before any .cursorignore exists: .gitignore, Cursor's default list, and your global patterns, which start empty.

for a middle

Name what the default list covers and what it misses, such as keys and credential files, and which surfaces an ignored file is hidden from.

for a senior

Commit a .cursorignore for repositories with sensitive paths, because global patterns are per user, and remember ignoring is not containment against terminal reads.

for a principal

Decide whether ignore patterns are left to each developer or set centrally; on Enterprise the dashboard holds team-wide patterns, which trades local flexibility for consistency.

## Where Cursor's ignore patterns come from Cursor reads your project to power its AI features, and it decides what those features may read from several pattern sources. Before anyone on the team writes a `.cursorignore`, three of them are already in force or waiting to be filled: | Source | Where it lives | Content out of the box | |---|---|---| | `.gitignore` | The repository | Whatever the repository already ignores in Git | | Default ignore list | Built into Cursor | Lock files, `.env*`, version-control folders, binaries, documents, media, archives, dependency and cache folders | | Global ignore patterns | Your user settings | Empty | A fourth source, a `.cursorignore` file in the project root, adds repository-specific patterns on top. On Enterprise plans the team dashboard also has a **Cursor Ignore Configuration** section where admins set ignore patterns for files and directories. ## The default ignore list, grouped Cursor's ignore-file reference prints the full list. In groups: - **Lock files**: `package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, `composer.lock`, `Gemfile.lock`, `bun.lockb`, plus `*.lock` and `*.lockb`. - **Environment files**: `.env*`, which matches `.env`, `.env.local` and `.env.example` alike. - **Version-control folders**: `.git/`, `.svn/`, `.hg/`, `.bzr/`. - **Binaries**: `*.exe`, `*.dll`, `*.so`, `*.bin`, `*.vsix`, `*.rlib`. - **Documents, data and media**: `*.pdf`, `*.csv`, `*.xlsx`, `*.parquet`, images including `*.png` and `*.svg`, audio, video and font files. - **Archives and disk images**: `*.zip`, `*.tar.gz`, `*.7z`, `*.dmg`, `*.iso`. - **Dependency and cache folders**: `node_modules/`, `.venv/`, `__pycache__/`, `.next/`, `.gradle/`, `.pytest_cache/`, `.yarn/`. Notice what is *not* on it: `*.pem`, `*.key`, `id_rsa`, `credentials.json`, `secrets.json`. A private key or a credentials file that the repository does not gitignore stays readable by Agent until someone adds a pattern for it. ## Global ignore patterns The global list in user settings applies to every project you open, so you do not repeat the same entries per repository. It is **empty by default**. Cursor's reference suggests the patterns worth adding first: 1. Environment files: `**/.env`, `**/.env.*` 2. Credentials: `**/credentials.json`, `**/secrets.json` 3. Keys: `**/*.key`, `**/*.pem`, `**/id_rsa` These are personal settings. They protect your editor, not a teammate's, which is why a repository that holds sensitive paths should also carry its own committed `.cursorignore`. ## What "ignored" blocks Per Cursor's reference, an ignored file is blocked from: - Agent's file reading, and codebase search - Tab and Inline Edit - @-mention references in the chat It is not blocked from terminal commands or MCP tools that Agent runs: those run outside Cursor's file access controls, and Cursor's own guardrails page calls `.cursorignore` a convenience rather than a security boundary. ## Overriding a default Every automatic exclusion can be overridden from `.cursorignore` with a `!` prefix. A common case: `.env.example` documents the variables a service needs and is safe to show Agent, but `.env*` hides it. A line `!.env.example` in `.cursorignore` brings it back. The same works for a small `*.csv` test fixture Agent needs to read. ## Why the defaults look the way they do Cursor gives two reasons for ignoring files, and the default list serves both: - **Performance and accuracy.** Large generated files, binaries, media and third-party code such as `node_modules/` add noise without value; in a large monorepo, excluding irrelevant portions makes file discovery more accurate. - **Security.** Environment files commonly hold credentials, so `.env*` is excluded up front, and Cursor's help page notes that secrets and credentials are safer excluded from AI context. Cursor's reference adds a caveat: while Cursor blocks ignored files, complete protection is not guaranteed due to LLM unpredictability. The list is therefore a sensible baseline for noise, and only a partial one for secrets. ## When Agent cannot see a file The reverse problem is just as common: Agent cannot find something it should. Cursor's troubleshooting page gives the order to check: 1. The project's `.cursorignore`, since listed files are blocked from Agent, codebase search and @-mentions. 2. The `.gitignore`, whose patterns also keep Agent from discovering files. 3. Reindexing, from the command palette by searching for "Reindex". A file that matches a default, such as a `*.csv` fixture or `.env.example`, will fail the same way until it is re-included. ## Common mistakes - Believing only `.cursorignore` keeps files out, while gitignored files stay visible to Agent. - Adding lock files and `.env` files by hand, not knowing the defaults already cover them. - Assuming private keys and credential files are covered by a default. - Thinking an ignored file is hidden from Agent but still feeds Tab suggestions.

  • A repository's .env.example documents required variables, but Cursor's Agent cannot read it. Why, and what fixes it?
    Cursor's default ignore list contains `.env*`, which matches `.env.example` as well as real secrets files. Add `!.env.example` to the project's `.cursorignore`: a `!` prefix there overrides the default list and `.gitignore` for that path.
  • A repository commits credentials.json for a local emulator. Does Cursor ignore it by default?
    No. The default list covers `.env*`, lock files, binaries, media and similar, not `*.json` credentials or `*.pem` keys. Add `**/credentials.json` to the repository's `.cursorignore`, or to your global ignore patterns, which Cursor's reference suggests for exactly these files.

  • Gitignored files stay visible to Agent; only .cursorignore keeps files out.
  • Cursor's global ignore list ships with key and credential patterns.
  • Lock files and .env files are readable until you list them yourself.
  • An ignored file is hidden from Agent but still feeds Tab and inline edit.
  • An ignored file becomes readable as soon as you @-mention it.