Clarify documentation for caching

[gronke]

A cache file is deleted when both conditions apply:

1. cacheFile option is pointing to an existing file
2. cache option is set to false

In my opinion this behavior is a little confusing, because the combination of --cache false and some valid path as --cache-file option is not likely. I would prefer to manually delete the specified cache file instead of running eslint once with at least the parameters from above and then run it again to re-create the cache. In case of the default .eslintcache file the behavior makes sense in this context when only --cache false option is set, but I would not expect the cache feature to create or delete anything when it is disabled.

Maybe an option, that allows to skip reading the cache file while results were still written to the cache file, could address the same need in a more intuitive way. (e.g. --flush-cache)

Want to back this issue? Post a bounty on it! We accept bounties via Bountysource.

[eslintbot]

@gronke Thanks for the issue! If you're reporting a bug, please be sure to include:

1. The version of ESLint you are using (run eslint -v)
2. What you did (the source code and ESLint configuration)
3. The actual ESLint output complete with numbers
4. What you expected to happen instead

Requesting a new rule? Please see Proposing a New Rule for instructions.

[nzakas]

I'm a little unclear on what you're asking for.

At first glance, it seems like this may be a bug where ESLint can't properly delete the cache file if a custom cache file is used. However, one could argue that this is expected behavior because specifying your own cache file is an indication that you know what you're doing and want to manage it yourself.

When ESLint is managing the cache, it makes sense to delete the cache file when caching is disabled. That's because running ESLint without the cache automatically invalidates the data in the cache. It's no longer safe to use that data because we don't know what has changed.

So, I'm not sure what part of this we would consider a problem that needs addressing.

[gronke]

We can reduce the problem to the question if a disabled feature (cache: false) should do any write/delete actions. By disabling the cache I'd expect neither to read or write the cache, but also not to delete existing cache files.

I'd prefer to manually remove the file to clear the cache or to set a flag that just skips reading the cache. But that's just an opinion and I might be picking nits here.

[nzakas]

If you want to manually control the deletion of the file, you can specify an alternate location using --cache-file. I'm just not convinced that everyone using --cache wants to manually delete the file, as that seems like an easy thing to forget and end up in a bad state.

[gronke]

What if somebody wants to run eslint with different configurations. For example on the whole codebase with cache enabled and on some specific files always without touching the cache at all

eslint --cache lib/*.js
eslint lib/some-file.js
# Would expect the cache to be still valid from the first command
eslint --cache lib/*.js

On the other hand a user could want to add results to the cache, but not use existing entries for those files

eslint --cache lib/*.js
# Enforce cache update of lib/some-file.js
eslint --cache --skip-cache lib/some-file.js

And for those who entirely want to clear the cache and wipe all entries this flag suits

# Delete cache and build a new cache index
eslint --cache --flush-cache lib/*.js

All of the above can be achieved by playing with the cache location, but it seems less intuitive to me.

---

The used cache framework file-entry-cache looks at mtime and size of a file to determine if it was changed, so the cache will only be used if none of those two parameters changed.

With that in mind, the risk of having an outdated cache file reduces pretty much to bloating the cache when it is not flushed from time to time in a fast moving project.

(In our context hash sums also look affordable, because that really tells us if the file was changed or not.)

[nzakas]

I'm uncomfortable with making the leap to the use cases you're theorizing. We don't have any evidence that people are wanting to support such cases, and your primary use case, managing the cache file yourself, is already supported.

I'm happy to update the docs to make the current behavior clearer.

[gronke]

@nzakas please feel free to close this issue. As you pointed out this changes would not add a feature that wouldn't have been accessible by playing with cacheLocation and cache together. Do you want me to create an issue to determine the use of file hashes instead of the file size when an mtime change was detected?

[nzakas]

I'll leave this open to make the docs clearer.

We discussed using file hashes a while back and determined they wouldn't offer much, iirc. Please search through closed issues before opening a new one for that.

[dominicbarnes]

I recently ran into an issue when using linter-eslint in Atom.

I was using --cache in my own repo/project, but linter-eslint is running w/o specifying cache: true and my .eslintcache file was being deleted for no apparent reason. This was confusing to me, and I never expected that leaving out cache: true would delete the cache from previous runs.

Now that I've read through this thread, I can kinda see why it is the way it is, but that didn't make this experience any less confusing.