compare-builds

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Compare Builds

构建对比

Quick Start

快速入门

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

Run
```
tuist build list --json
```
to find builds on each branch.
Run
```
tuist build show <build-id> --json
```
for both base and head builds.

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

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

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

你通常会拿到两个构建标识符（可以是ID、仪表盘URL或分支名），按照以下步骤操作：

执行
```
tuist build list --json
```
查找每个分支上的构建记录。
分别为基准构建和待对比构建执行
```
tuist build show <build-id> --json
```
查看详情。

获取子资源详情：目标（

tuist build xcode target list <id> --json

）、问题（

tuist build xcode issue list <id> --json

）以及缓存任务（

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

）。

对比构建时长、状态、缓存命中率和其他指标。
总结回归问题、优化点和建议。

如果仅提供了一个标识符，则使用项目的默认分支作为基准。

Step 1: Resolve Builds

步骤1：解析构建记录

If base/head are build IDs or dashboard URLs

如果基准/待对比项是构建ID或仪表盘URL

Fetch each directly:

bash

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

直接拉取对应信息：

bash

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:

bash

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

列出每个分支的最近构建记录，选择最新的一条：

bash

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
```
.

如果未提供基准，使用项目的默认分支（通常是
```
main
```
）。
如果未提供待对比分支，使用
```
git rev-parse --abbrev-ref HEAD
```
检测当前git分支。

Step 2: Fetch Sub-Resource Details

步骤2：获取子资源详情

After fetching both builds with

tuist build show <id> --json

, drill down into sub-resources for a deeper comparison.

使用

tuist build show <id> --json

拉取到两次构建的信息后，深入查看子资源信息以进行更深度的对比。

Compare targets

对比目标

bash

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.

bash

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

查找状态发生变更（例如从成功变为失败）或时长出现明显变化的目标。

Compare issues

对比问题

bash

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.

bash

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

查找待对比构建中新引入的警告或错误。

Compare cache tasks

对比缓存任务

bash

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.

bash

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

识别哪些特定目标出现了缓存命中或未命中，以及两次构建间的缓存情况是否发生了变化。

Step 3: Compare Top-Level Metrics

步骤3：对比核心指标

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.

拉取到两次构建的信息后，对比以下内容：

指标	检查项
`duration`	如果待对比构建比基准慢10%以上需要标记
`status`	如果基准构建成功但待对比构建失败需要标记
`cacheable_tasks_count`	注意任务数量是否发生变化
`cacheable_task_local_hits_count`	对比本地缓存命中次数
`cacheable_task_remote_hits_count`	对比远端缓存命中次数
缓存命中率	`(本地命中次数 + 远端命中次数) / 可缓存任务总数 * 100`
`category`	注意是否一个是 `clean` （全量构建）另一个是 `incremental` （增量构建）（这种情况下时长对比参考价值较低）
`scheme` / `configuration`	确保两次构建使用了相同的scheme和配置，保证对比公平

计算缓存未命中差值：

基准未命中数 - 待对比未命中数

。正数说明待对比构建未命中更少（优化），负数说明出现了性能回归。

Step 4: Investigate Duration Regressions

步骤4：排查耗时回归问题

If the head build is significantly slower:

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

如果待对比构建速度明显变慢：

检查构建
```
category
```
是否不同（全量和增量构建不具备直接可比性）。
检查缓存命中率是否下降，这是构建时长增加的常见原因。
如果两次都是增量构建且缓存命中率相近，则回归问题大概率出在编译时间上。

Step 5: Investigate Cache Changes

步骤5：排查缓存变更

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.

对比缓存统计数据：

命中率下降：可能原因包括依赖变更、构建设置修改或Xcode版本更新。
命中率提升：通常是因为缓存预热更充分或源码变更更少。
任务数量变化：说明有新增或移除的目标。

Step 6: Check Build Context

步骤6：检查构建上下文

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.

对比环境细节：

```
xcode_version
```
和
```
macos_version
```
：不同版本会影响构建时长和缓存有效性。
```
is_ci
```
：CI构建和本地构建可能有不同的性能特征。
```
git_branch
```
和
```
git_commit_sha
```
：验证构建来自预期的提交。

Summary Format

总结格式

Produce a summary with:

Overall verdict: Better, worse, or neutral compared to base.
Duration: Absolute and percentage change.
Cache hit rate: Change in hit rate with explanation.
Status: Any status changes (pass to fail or vice versa).
Environment: Note any environment differences that affect comparability.
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

输出的总结需要包含以下内容：

整体结论：和基准相比是更优、更差还是无差异。
时长：绝对值和百分比变化。
缓存命中率：命中率变化及原因说明。
状态：任何状态变更（从通过到失败或反过来）。
环境：标注任何影响可比性的环境差异。
建议：基于发现给出可落地的后续步骤。

示例：

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

已解析基准和待对比两次构建的信息
已拉取子资源详情（目标、问题、缓存任务）
已对比时长、缓存和状态指标
已识别所有回归问题的根本原因
已提供可落地的优化建议