compare-builds

name	compare-builds
description	Compares two Xcode build runs to identify duration regressions, cache changes, and new issues. Can be invoked with build IDs, dashboard URLs, or branch names (e.g. `tuist compare-builds --base main --head feature-branch`).

Compare Builds

Quick Start

You'll typically receive two build identifiers (IDs, dashboard URLs, or branch names). Follow these steps:

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.

If only one identifier is provided, use the project's default branch as the baseline.

Step 1: Resolve Builds

If base/head are build IDs or dashboard URLs

Fetch each directly:

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

If base/head are branch names

List recent builds on each branch and pick the latest:

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

Then fetch full details with 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

After fetching both builds with tuist build show <id> --json, drill down into sub-resources for a deeper comparison.

Compare targets

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

Look for targets that changed status (e.g., success to failure) or had significant duration changes.

Compare issues

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

Look for new warnings or errors introduced in the head build.

Compare cache tasks

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

Identify which specific targets had cache misses or hits and whether that changed between builds.

Step 3: Compare Top-Level Metrics

After fetching both builds, compare:

Metric	What to check
duration	Flag if head is >10% slower than base
status	Flag if base succeeded but head failed
cacheable_tasks_count	Note if task count changed
cacheable_task_local_hits_count	Compare local hit counts
cacheable_task_remote_hits_count	Compare remote hit counts
Cache hit rate	(local_hits + remote_hits) / cacheable_tasks_count * 100
category	Note if one is clean and the other incremental (makes duration comparison less meaningful)
scheme / configuration	Ensure both builds used the same scheme and configuration for a fair comparison

Compute the cache miss delta: base_misses - head_misses. Positive means head has fewer misses (improvement). Negative means regression.

Step 4: Investigate Duration Regressions

If the head build is significantly slower:

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

Compare cache statistics:

• 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

Compare environment details:

• 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

Produce a summary with:

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.

Example:

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