ccache -z and -C: Reset Stats and Clear the Cache
ccache -z zeroes the statistics counters and ccache -C empties the cache entirely.
To measure how a single CI run performed you reset the counters first; to force a guaranteed cold build you clear the cache. The two are different and easy to confuse.
What it does
ccache -z (--zero-stats) resets the hit/miss counters to zero without touching cached objects, so a following ccache -s reflects only the current run. ccache -C (--clear) deletes all cached objects, forcing the next build to be a full miss. -C does not reset stats; -z does not delete objects.
Common usage
ccache -z # reset counters before a build
cmake --build build
ccache -s # stats for just this build
ccache -C # clear the entire cache (cold rebuild)Options
| Flag | What it does |
|---|---|
| -z / --zero-stats | Reset statistics counters to zero |
| -C / --clear | Remove all cached objects |
| -s | Print stats (run after -z to measure one build) |
| --cleanup | Enforce size limits without clearing everything |
In CI
Call ccache -z at the start of the compile step and ccache -s at the end to log a clean per-run hit rate, which makes regressions in caching obvious in the history. Reserve ccache -C for a manual "cache seems poisoned" reset; do not clear on every run or you lose the entire benefit of persisting CCACHE_DIR.
Common errors in CI
Clearing with -C every build and then wondering why hit rate is always 0% is a common self-inflicted mistake; remove the -C. Running -z but reading stats from a step that re-restored the cache can show misleading numbers; keep zero, build, and stats in the same step. -C on a read-only CCACHE_DIR fails with a permissions error.