Compare Cache Runs

Quick Start

1. Run

   tuist cache-run list --json

   to find cache runs on each branch.
2. Run

   tuist cache-run show <id> --json

   for both base and head cache runs.
3. Compare duration, status, and cache hit rates.
4. Summarize cache changes with root cause analysis.

Step 1: Resolve Cache Runs

If base/head are cache run IDs or dashboard URLs

tuist cache-run show <base-id> --json
tuist cache-run show <head-id> --json

If base/head are branch names

tuist cache-run list --git-branch <base-branch> --json --page-size 1
tuist cache-run list --git-branch <head-branch> --json --page-size 1

tuist cache-run show <id> --json

Defaults

• If no base is provided, use the project's default branch (usually

  main

  ).
• If no head is provided, detect the current git branch.

Step 2: Compare Top-Level Metrics

duration

status

cacheable_targets

local_cache_target_hits

remote_cache_target_hits

is_ci

• Base:

  (local_hits + remote_hits) / cacheable_targets * 100

• Head: same formula
• Delta:

  head_rate - base_rate

Step 3: Analyze Cache Invalidation

tuist cache

tuist generate

1. A "root cause" target has a direct change (source file modified, build setting changed, etc.)
2. All targets that depend on the root cause target also get invalidated because their

   dependencies

   hash changes.
3. This cascade can invalidate many targets from a single root change.

Identifying root cause targets

1. Check

   git diff

   between the base and head commits to see which files changed.
2. Map changed files to their Tuist targets/modules.
3. Targets with direct source changes are likely root causes.
4. Targets that only changed due to dependency hash cascading are secondary invalidations.

Common root causes of cache invalidation

Step 4: Assess Impact

• Expected: Source files were intentionally changed, causing expected cache misses.
• Unexpected: No source changes but cache was invalidated (build settings, Xcode version, etc.).
• Cascade: A small change invalidated many downstream targets.

tuist cache

• Cache warming strategy: Was the cache run warming from scratch or incrementally?
• The

  command_arguments

  field can reveal if different flags were used.

Summary Format

1. Overall verdict: Cache hit rate improved, regressed, or stable.
2. Cache hit rate: Base rate vs head rate with delta.
3. Duration: Absolute and percentage change.
4. Root cause targets: Which targets had direct changes.
5. Cascade impact: How many targets were invalidated due to dependency cascading.
6. Recommendations: How to minimize cache invalidation.

Cache Run Comparison: base (run-123 on main) vs head (run-456 on feature-x)

Duration: 95.2s -> 142.8s (+50%) -- REGRESSION
Cache hit rate: 88% (44/50) -> 60% (30/50) (-28%) -- REGRESSION
Status: success -> success

Root cause: CoreModule had source changes (5 files modified).
This cascaded to 14 downstream targets that depend on CoreModule.

Cache invalidation breakdown:
- Direct changes: CoreModule (sources changed)
- Cascade: UIKit, Networking, Analytics, + 11 others (dependency hash changed)

Recommendations:
- Consider splitting CoreModule into smaller, more focused modules
- Use interface/implementation module pattern for frequently-changed modules
- Run `tuist cache` on the feature branch after rebasing to warm caches

Done Checklist

• Resolved both base and head cache runs
• Compared duration and cache hit rates
• Identified root cause targets for cache invalidation
• Analyzed cascade impact
• Provided actionable recommendations for reducing cache misses