Add --cache CLI option (#12800)

* Install `file-entry-cache` and types

* Implement `FormatResultsCache`

* Add `--cache` and `--cache-location` option

* Implement `--cache` and `--cache-location`

* Add tests for `--cache`

* Add tests for `--cache-location`

* Avoid spellcheck error

* Update snapshots for new options

* Add `groupBy` for website

* Use `fs.promises` instead of `fs/promises`

* Use `rimraf` instead of `fs.rm`

* Fix properties order of `options`

* Install `find-cache-dir` and types

* Change default cache file location to `node_modules/.cache/prettier`

* Fix tests following to change default cache file location

* Update snapshots for changing default cache file location

* Set `os.tmpdir()` as a fallback for default cache dir

* Add docs for `--cache` and `--cache-location`

* Use `sdbm` instead of `node:crypto`

* Add changelog

* Fix `getHashOfOptions`

* Remove `cache-location`

* `prettiercache` -> `prettier-cache`

* Remove cache file when run Prettier without `--cache` option

* Implement `--cache-strategy`

* Add tests for invalid cache strategy

* Fix lint problems

* Tweaks tests

* Add tests for timestamp

* Add tests for `--cache-strategy`

* Add docs for cache-strategy

* Address review

* Fix `findCacheFile`

* Use Set.prototype.has

* Throw error with --stdin-filepath

* Update snapshots

* Fix error for cache and stdin

* Use string constructor instead of toString

* Update changelog

* Use flag validation

* Fix `cache-strategy` definition

* Update docs

* Mark highlihgt

* Throw error for `--cache-strategy` without `--cache`

* Update docs

* Fix typo

* Updates snapshots

* Update docs/cli.md

Co-authored-by: Simon Lydell <simon.lydell@gmail.com>

* Fix error message

* Remove `:::` syntax

* Defaults `content`

* Update docs

* Fix by Prettier

Co-authored-by: Simon Lydell <simon.lydell@gmail.com>

docs/cli.md

@@ -204,3 +204,35 @@ Prevent errors when pattern is unmatched.
 ## `--no-plugin-search`
 
 Disable plugin autoloading.
+
+## `--cache`
+
+If this option is enabled, the following values are used as cache keys and the file is formatted only if one of them is changed.
+
+- Prettier version
+- Options
+- Node.js version
+- (if `--cache-strategy` is `metadata`) file metadata, such as timestamps
+- (if `--cache-strategy` is `content`) content of the file
+
+```bash
+prettier --write --cache src
+```
+
+Running Prettier without `--cache` will delete the cache.
+
+Also, since the cache file is stored in `./node_modules/.cache/prettier/.prettier-cache`, so you can use `rm ./node_modules/.cache/prettier/.prettier-cache` to remove it manually.
+
+> Plugins version and implementation are not used as cache keys. We recommend that you delete the cache when updating plugins.
+
+## `--cache-strategy`
+
+Strategy for the cache to use for detecting changed files. Can be either `metadata` or `content`.
+
+In general, `metadata` is faster. However, `content` is useful for updating the timestamp without changing the file content. This can happen, for example, during git operations such as `git clone`, because it does not track file modification times.
+
+If no strategy is specified, `content` will be used.
+
+```bash
+prettier --write --cache --cache-strategy metadata src
+```