docs: Improve documentation on statistics counters and --zero-stats

After discussion with Otto Kekäläinen in #1639.

Co-authored by: Otto Kekäläinen <otto@kekalainen.net>

diff --git a/doc/manual.adoc b/doc/manual.adoc
index 174b1d0d1d50911203d349b8265ee42c2702e1ab..ce2f803b40900e3cf4d0ef089bfc4bc70e8f4b39 100644 (file)
--- a/doc/manual.adoc
+++ b/doc/manual.adoc
@@ -183,7 +183,8 @@ documentation.
 *-s*, *--show-stats*::
 
     Print a summary of configuration and statistics counters in human-readable
-    format. Use `-v`/`--verbose` once or twice for more details.
+    format. Use `-v`/`--verbose` once or twice for more details. See
+    <<_cache_statistics,Cache statistics>> for more information.
 
 *-v*, *--verbose*::
 
@@ -1440,6 +1441,18 @@ limit being reached or due to explicit `ccache -c` calls), overall hit rate, hit
 rate for <<The direct mode,direct>>/<<The preprocessor mode,preprocessed>> modes
 and hit rate for local and <<config_remote_storage,remote storage>>.
 
+The statistics counters are not used by ccache itself during builds. This means
+that you can safely reset them at any time using `ccache --zero-stats` without
+affecting the build process. For example, you might reset them before a build so
+that `ccache --show-stats` will only summarize the results from that specific
+build. Alternatively, you can set <<config_stats_log,*stats_log*> before
+starting the build and then run `ccache --show-log-stats` afterward to view
+build-specific statistics. This approach allows the statistics counters to
+continue tracking the entire lifetime of the cache while still giving you
+detailed information for individual builds. Another advantage of *stats_log* is
+that it collects statistics without interference from other concurrent builds
+that access the same cache.
+
 The summary also includes counters called "`Errors`" and "`Uncacheable`", which
 are sums of more detailed counters. To see those detailed counters, use the
 `-v`/`--verbose` flag. The verbose mode can show the following counters: