From e799280a6fe403e9ef766c2343effaf4423da65a Mon Sep 17 00:00:00 2001 From: Joel Rosdahl Date: Wed, 8 Oct 2025 21:54:16 +0200 Subject: [PATCH] docs: Improve documentation on statistics counters and --zero-stats MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit After discussion with Otto Kekäläinen in #1639. Co-authored by: Otto Kekäläinen --- doc/manual.adoc | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/doc/manual.adoc b/doc/manual.adoc index 174b1d0d..ce2f803b 100644 --- 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 <>/<> modes and hit rate for local and <>. +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 < 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: -- 2.47.3