Compare Builds

Quick Start

1. Run

   tuist build list --json

   to find builds on each branch.
2. Run

   tuist build show <build-id> --json

   for both base and head builds.
3. Fetch sub-resource details: targets (

   tuist build xcode target list <id> --json

   ), issues (

   tuist build xcode issue list <id> --json

   ), and cache tasks (

   tuist build xcode cache-task list <id> --json

   ).
4. Compare duration, status, cache hit rates, and other metrics.
5. Summarize regressions, improvements, and recommendations.

Step 1: Resolve Builds

If base/head are build IDs or dashboard URLs

tuist build show <base-id> --json
tuist build show <head-id> --json

If base/head are branch names

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

tuist build 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 with

  git rev-parse --abbrev-ref HEAD

  .

Step 2: Fetch Sub-Resource Details

tuist build show <id> --json

Compare targets

tuist build xcode target list <base-id> --json
tuist build xcode target list <head-id> --json

Compare issues

tuist build xcode issue list <base-id> --json
tuist build xcode issue list <head-id> --json

Compare cache tasks

tuist build xcode cache-task list <base-id> --json
tuist build xcode cache-task list <head-id> --json

Step 3: Compare Top-Level Metrics

duration

status

cacheable_tasks_count

cacheable_task_local_hits_count

cacheable_task_remote_hits_count

(local_hits + remote_hits) / cacheable_tasks_count * 100

category

clean

incremental

scheme

configuration

base_misses - head_misses

Step 4: Investigate Duration Regressions

1. Check if the

   category

   differs (clean vs incremental builds are not directly comparable).
2. Check if cache hit rate dropped, which would explain longer builds.
3. If both are incremental with similar cache rates, the regression is likely in compilation time.

Step 5: Investigate Cache Changes

• Hit rate dropped: Possible causes include dependency changes, build setting changes, or Xcode version updates.
• Hit rate improved: Likely due to better cache warming or fewer source changes.
• Task count changed: New targets added or removed.

Step 6: Check Build Context

• xcode_version

  and

  macos_version

  : Different versions can affect build times and cache validity.

• is_ci

  : CI vs local builds may have different performance characteristics.

• git_branch

  and

  git_commit_sha

  : Verify the builds are from the expected commits.

Summary Format

1. Overall verdict: Better, worse, or neutral compared to base.
2. Duration: Absolute and percentage change.
3. Cache hit rate: Change in hit rate with explanation.
4. Status: Any status changes (pass to fail or vice versa).
5. Environment: Note any environment differences that affect comparability.
6. Recommendations: Actionable next steps based on findings.

Build Comparison: base (abc123 on main) vs head (def456 on feature-x)

Duration: 45.2s -> 62.8s (+39%) -- REGRESSION
Cache hit rate: 85% -> 72% (-13%) -- 8 new cache misses
Status: success -> success

Root cause: Cache hit rate dropped due to 8 targets with invalidated caches.
The dependency hash changed for FeatureModule, cascading to 7 downstream targets.

Recommendations:
- Investigate why FeatureModule's cache was invalidated
- Consider splitting large targets to reduce cascade impact

Done Checklist

• Resolved both base and head builds
• Fetched sub-resource details (targets, issues, cache tasks)
• Compared duration, cache, and status metrics
• Identified root causes for any regressions
• Provided actionable recommendations