How does ESLint's --cache decide a file can be skipped, and why can cached results be wrong on CI checkouts or with typed rules?
answer
- per-file, never cross-file
- the file plus its config
- metadata by default
- clones reset modification times
- content strategy hashes the file
basics
~20 sESLint's --cache reuses a file's stored result while the file and its config look unchanged, judged by modification time and size by default. A fresh clone resets those, so use --cache-strategy content; cross-file rules, typed ones included, can report stale results.
solid answer
~50 s`--cache` writes `.eslintcache` in the directory ESLint runs from and skips a file when its stored entry is still valid. Validity is checked per file: the file itself, by modification time and size under the default `--cache-strategy metadata` or by a hash of its contents under `content`, plus a hash of the config that applies to it, which also covers the ESLint and Node.js versions. On a fresh `git clone` every modification time is new, so `metadata` treats every file as changed and the restored cache is useless; `content` fixes that. ESLint does not track dependencies between files, so a file's result is reused even when a module it imports changed. Type-aware rules from typescript-eslint and rules that resolve imports can therefore miss new problems or keep reporting fixed ones, and typescript-eslint does not recommend `--cache`.
code
bash · 3 lines# CI: keep the cache where the pipeline restores it,
# and compare contents, because a clone resets modification times
npx eslint --cache --cache-strategy content --cache-location .cache/eslint/ .go deeper
Know that --cache stores .eslintcache and lints only changed files, and that a later run without --cache deletes that file.
Explain the validity check: the file by modification time or content, plus a hash of the config that applies to it, ESLint version and Node.js version.
Explain a cache that never hits in CI, since clones reset modification times and content fixes that, and why typed or import-resolving rules go stale under --cache.
Choose where accuracy matters more than speed: a local cached run for feedback, and a merge gate that runs typed rules without the cache.
## What `--cache` stores With `--cache`, ESLint records information about every file it processed so that later runs lint only the files that changed. By default the cache is a file named `.eslintcache`, created in the directory where the `eslint` command runs. `--cache-location` moves it: give a file path, or a directory with a trailing `/`, in which case ESLint names the file after a hash of the working directory. Two lifecycle rules catch people out: - **A run without `--cache` deletes the cache file.** ESLint does this because a non-cached run may produce results that make the old cache wrong. A pipeline that mixes cached and uncached runs keeps starting cold. - **Autofixed files are not cached.** After `--fix` changes a file, the next run that applies no fix to it stores it. ## How a cached result is judged valid For each file, ESLint asks two questions: 1. **Has the file changed?** Under `--cache-strategy metadata`, the default, it compares modification time and size. Under `--cache-strategy content`, it compares a hash of the file's contents. 2. **Has the config for that file changed?** ESLint hashes the computed config together with the ESLint version and the Node.js version. Change a rule's severity or options for that file and its entry is discarded. If both answers are no, ESLint reuses the stored messages without parsing the file. Nothing else is consulted. Plugins enter the config hash only by name and version, and only when a plugin declares them in its `meta`; ESLint's Node.js API documentation still warns that upgrading plugins does not clear the cache, so deleting the file after a plugin upgrade is the safe habit. | Strategy | Detects change by | Good for | Weak spot | |---|---|---|---| | `metadata` (default) | modification time and size | a developer's machine, where unchanged files keep their times | any checkout that rewrites modification times | | `content` | hash of the file's contents | CI restoring a cache into a fresh clone | every file must be read to compute its hash | ## Why CI checkouts defeat the default Git does not store modification times. A fresh `git clone` stamps every file with the time of the checkout, so when a pipeline restores yesterday's `.eslintcache` into a new clone, every file looks changed under `metadata` and ESLint lints the whole repository again. The cache was restored and gave nothing. The documented fix is `--cache-strategy content`, which compares contents and ignores timestamps. Restoring the file between jobs is the pipeline's own cache mechanism, and choosing its key is a CI caching question rather than an ESLint one. ## Why cross-file rules go stale ESLint caches per file and **does not track dependencies between files**. Its documentation spells out both failure directions: - A module changes in a way that introduces a problem in an unchanged file that imports it. With `--cache`, that problem is not reported until the importing file or its config changes. - A problem in a file that was already fixed by changing another file keeps being reported from the cache. The rules affected are those whose result depends on other files: **type-aware rules**, such as the typed rules of typescript-eslint, and rules that resolve imports across modules. typescript-eslint's FAQ says ESLint's cache only works reliably for untyped rules, "and even then, not always", and that it does not recommend using `--cache`. ESLint's own advice is to run without `--cache` whenever you need accurate results from such rules. ## Diagnosing a suspicious cached result When a cached run disagrees with what you expect, work through it in order: 1. Run the same command without `--cache`. If the problem appears or disappears, the cache was stale, and the cause is a cross-file rule or a change ESLint does not track. 2. Check the strategy. A cache that never hits on a fresh checkout points at `metadata` meeting new modification times. 3. Check the location. A cache file that keeps vanishing usually means some other command in the same directory runs ESLint without `--cache` and deletes it. 4. Delete the cache after upgrading ESLint plugins, parsers or typescript-eslint, rather than trusting it to notice. ## A reasonable setup - On developer machines, `--cache` with the default strategy is cheap and mostly right for untyped rules. - In CI, either run without the cache, or use `--cache --cache-strategy content` with a fixed `--cache-location` the pipeline restores. - If the config enables type-aware or import-resolving rules, make the merge gate a run without `--cache`, so a stale entry cannot let a new problem through. - Never alternate cached and uncached runs on the same cache file, since the uncached run deletes it.
- A teammate's script runs `eslint --cache .` and then `eslint --format json .` for a report. Why is the cache always cold the next morning?A run without `--cache` deletes `.eslintcache`, because ESLint cannot know whether the old entries are still valid. The second command wipes what the first one built. Pass `--cache` on both runs, or give the cache its own `--cache-location` and only use it from cached runs.
- After a plugin upgrade, cached files still report a rule's old behaviour. Why?The cache entry is checked against the file and a hash of its computed config plus the ESLint and Node.js versions. A plugin is part of that hash only through the name and version it declares in its `meta`; a plugin that declares neither changes nothing ESLint checks, and ESLint's Node.js API documentation warns that plugin upgrades do not clear the cache. Delete the cache file after upgrading plugins.
A proofreader who re-reads a chapter only when its date stamp changes. Stamp every chapter afresh, as a clone does, and the whole book gets re-read; change chapter 3, which chapter 7 quotes, and chapter 7 is never re-checked.
- --cache re-lints a file when any module it imports has changed.
- Restoring .eslintcache into a fresh clone makes CI lint only changed files.
- Both cache strategies compare file contents, so the choice only affects speed.
- The cache stores results per directory, so editing one file re-lints its folder.
- Typed rules are safe with --cache because the type checker tracks dependencies.