skip to content

After adding `--ignore-path .prettierignore` to a `prettier --check .` script, why does Prettier 3 start failing on build output listed only in `.gitignore`?

level: seniorimportance: nice to knowfreq 8%

answer

  1. two default ignore files
  2. a flag that replaces, not adds
  3. repeat the flag to keep both
  4. node_modules skipped anyway
  5. prettier-ignore skips one node

basics

~10 s

By default Prettier 3 reads both ./.gitignore and ./.prettierignore. Passing --ignore-path replaces those defaults rather than adding to them, so paths only in .gitignore are formatted and checked again.

solid answer

~40 s

Without the flag, Prettier 3 reads two ignore files from the directory it runs in: `./.gitignore` and `./.prettierignore`, both in gitignore syntax. `--ignore-path` "overrides the default rather than adding to it", so `--ignore-path .prettierignore` drops `.gitignore` and the `dist/` or `coverage/` folders listed only there are suddenly checked, and fail. Fix it by removing the flag, or by repeating it for every file you want: `--ignore-path=.gitignore --ignore-path=.prettierignore`. Separately, version-control folders are always skipped, and so is `node_modules` unless you pass `--with-node-modules`. A vendored folder that must never be reformatted belongs in `.prettierignore`, which the editor integration also respects; `// prettier-ignore` excludes only the next AST node, not a file.

code

bash · 11 lines
bash
# Drops .gitignore: dist/ is checked and fails
npx prettier . --check --ignore-path .prettierignore

# Same as the default: both files are read
npx prettier . --check

# Defaults kept, one extra ignore file added
npx prettier . --check \
  --ignore-path=.gitignore \
  --ignore-path=.prettierignore \
  --ignore-path=.vendorignore

go deeper

for a junior

Recall that .prettierignore lists files Prettier must not format, and that node_modules is skipped automatically.

for a middle

Explain that Prettier 3 reads both .gitignore and .prettierignore by default, and when to use prettier-ignore comments instead of the ignore file.

for a senior

Spot the silent change: --ignore-path replaces the defaults, so generated files reappear; also know the cache's content default and that plugin upgrades are not in its key.

for a principal

Keep exclusions in files every tool reads, the ignore files, rather than in script flags, so editors, local runs and CI agree on what is formatted.

## What Prettier ignores by default In Prettier 3, three sources decide which files are skipped before formatting or checking: 1. **Built-in folders**: version-control directories (`.git`, `.svn`, `.hg` and similar) and `node_modules`. The latter is formatted only with `--with-node-modules`. 2. **`./.gitignore`**, the one in the directory Prettier is run from. 3. **`./.prettierignore`**, likewise in the working directory, written in gitignore syntax. The CLI's own option table shows the default of `--ignore-path` as the list `[".gitignore", ".prettierignore"]`. So in an ordinary repository, build output already listed in `.gitignore` is never checked, even with no `.prettierignore` at all. ## `--ignore-path` replaces the defaults The CLI docs are explicit: "Specifying an `--ignore-path` overrides the default rather than adding to it." The flag accepts several values by repetition. | Command | Ignore files read | |---|---| | `prettier . --check` | `.gitignore`, `.prettierignore` | | `prettier . --check --ignore-path .prettierignore` | `.prettierignore` only | | `prettier . --check --ignore-path=.gitignore --ignore-path=.prettierignore --ignore-path=.vendorignore` | all three | That explains the failure in the question. Someone added `--ignore-path .prettierignore`, probably believing it was needed to make Prettier read that file. It was already read; the flag removed `.gitignore` from the list, and the generated `dist/` folder that only `.gitignore` mentioned began failing `prettier --check` with exit code `1`. ## Choosing the right tool for each exclusion On the coworking-space portal, the vendored `public/legacy/` folder must never be reformatted: - **Whole files and folders**: add `public/legacy` to `.prettierignore`. The docs recommend having one so that `prettier --write .` never mangles generated or vendored files, and "your editor will know which files _not_ to format". - **One construct in a file**: `// prettier-ignore` in JavaScript excludes **the next node in the AST**, for example a hand-aligned matrix. Markdown, CSS, YAML and HTML have their own comment forms, and Markdown supports a top-level range with `<!-- prettier-ignore-start -->` and `<!-- prettier-ignore-end -->`. - **A one-off command**: negative patterns such as `prettier . "!**/*.min.js" --check` exclude files without touching any ignore file. - **Unknown file types**: `--ignore-unknown` (`-u`) skips files Prettier has no parser for instead of exiting `2`. An `overrides` entry in `.prettierrc` is not an ignore mechanism: it changes the options used for matching files rather than excluding them. ## Ignored files and the cache Ignoring decides which files are processed; `--cache` decides which of those are re-processed. In Prettier 3: - the cache file lives at `node_modules/.cache/prettier/.prettier-cache` unless `--cache-location` says otherwise; - the key is the Prettier version, the options, the Node.js version and either the file's **content** or its **metadata**; - `--cache-strategy` defaults to **`content`**, unlike ESLint's cache, whose strategy defaults to `metadata`; - plugin versions are **not** part of the key, so delete the cache after upgrading a Prettier plugin; - running without `--cache` deletes the cache. The content strategy matters in CI and after `git clone`, which does not preserve modification times, so a metadata key would treat files as changed even when their content is not. ## Ignore files and monorepos Both default ignore files are read from the directory Prettier is run in, not from each formatted file's folder the way configuration is found. That asymmetry surprises monorepo users: - Running `prettier . --check` from the repository root reads the root `.gitignore` and `.prettierignore`; a `.prettierignore` inside `packages/web/` is not consulted. - Running the same command from `packages/web/` reads that package's files instead, and the root ones are not consulted. - Patterns in an ignore file use gitignore syntax: `public/legacy`, which contains a slash, is matched relative to the ignore file's own directory, while `**/*.min.js` matches minified files at any depth. The safest habit is to run Prettier from one place, usually the root, and keep one `.prettierignore` there. ## Checklist when Prettier touches a file it should skip - Is the file listed in `.prettierignore` or `.gitignore` **in the directory Prettier is run from**? - Does any script pass `--ignore-path`, silently dropping one of the defaults? - Is the file passed explicitly with an unusual extension that needs `--ignore-unknown`? - Is the exclusion really an `overrides` entry, which changes options but still formats?

  • The same script adds `--cache`. After upgrading a Prettier plugin, files format the old way. Why?
    Prettier's cache key is the Prettier version, the options, the Node.js version and the file content (the default `content` strategy). Plugin versions are not in the key, so unchanged files keep their cached result. Delete `node_modules/.cache/prettier/.prettier-cache`, or run once without `--cache`, which deletes it.
  • How do you keep one hand-aligned array exactly as written in an otherwise formatted file?
    Put `// prettier-ignore` on the line before it. Prettier then leaves the next AST node, the whole statement holding the array, untouched while formatting the rest of the file.

  • --ignore-path adds a file to the default ignore list
  • Prettier ignores only what .prettierignore lists
  • prettier-ignore at the top of a file skips the whole file
  • An overrides entry in .prettierrc stops those files being formatted
  • Prettier's cache defaults to the metadata strategy like ESLint's

Assumes Prettier 3 (3.9.9): the default ignore files are ./.gitignore and ./.prettierignore, and --cache-strategy defaults to content.