compare-generations

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Compare Generations

对比生成运行

Quick Start

快速开始

You'll typically receive two generation identifiers. Follow these steps:

Run
```
tuist generate list --json
```
to find generations on each branch.
Run
```
tuist generate show <id> --json
```
for both base and head generations.
Compare duration, status, and cache hit rates.
Summarize cache changes with root cause analysis.

你通常会收到两个生成标识符。请按照以下步骤操作：

运行
```
tuist generate list --json
```
查找各分支上的生成记录。
对基准（base）和目标（head）生成记录分别运行
```
tuist generate show <id> --json
```
。
对比耗时、状态和缓存命中率。
总结缓存变化并进行根因分析。

Step 1: Resolve Generations

步骤1：解析生成记录

If base/head are generation IDs or dashboard URLs

若基准/目标为生成ID或仪表板URL

Fetch each directly:

bash

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

直接获取每条记录：

bash

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

If base/head are branch names

若基准/目标为分支名称

List recent generations on each branch:

bash

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

Then fetch full details with

tuist generate show <id> --json

列出各分支上的近期生成记录：

bash

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

然后使用

tuist generate 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.

若未提供基准，使用项目的默认分支（通常为
```
main
```
）。
若未提供目标，自动检测当前git分支。

Step 2: Compare Top-Level Metrics

步骤2：对比顶层指标

After fetching both generations, compare:

Metric	What to check
`duration`	Flag if head is >10% slower
`status`	Flag if base succeeded but head failed
`cacheable_targets`	Note if target count changed
`local_cache_target_hits`	Compare local hit counts
`remote_cache_target_hits`	Compare remote hit counts
`is_ci`	Note if one is CI and the other local

Compute cache hit rates:

Base:

(local_hits + remote_hits) / cacheable_targets * 100

Head: same formula
Delta:
```
head_rate - base_rate
```

获取两条生成记录后，对比以下内容：

指标	检查要点
`duration`	若目标耗时比基准慢10%以上则标记
`status`	若基准成功但目标失败则标记
`cacheable_targets`	记录可缓存目标数量是否变化
`local_cache_target_hits`	对比本地缓存命中数量
`remote_cache_target_hits`	对比远程缓存命中数量
`is_ci`	记录是否一个为CI环境、另一个为本地环境

计算缓存命中率：

基准：

(本地命中数 + 远程命中数) / 可缓存目标数 * 100

目标：使用相同公式
差值：
```
目标命中率 - 基准命中率
```

Step 3: Analyze Cache Invalidation

步骤3：分析缓存失效原因

If cache hit rate dropped, the key question is: which target(s) caused the invalidation cascade?

Cache invalidation typically works like this:

A "root cause" target has a direct change (source file modified, build setting changed, etc.)
All targets that depend on the root cause target also get invalidated because their
```
dependencies
```
hash changes.
This cascade can invalidate many targets from a single root change.

若缓存命中率下降，核心问题是：哪些目标引发了失效连锁反应？

缓存失效的典型机制如下：

某个“根因”目标发生直接变更（源文件修改、构建设置变更等）。
所有依赖该根因目标的目标也会失效，因为它们的
```
dependencies
```
哈希值发生变化。
单次根变更可能引发大量目标失效的连锁反应。

Identifying root cause targets

识别根因目标

Without the module cache target detail endpoint (available via MCP), use these heuristics:

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

在没有模块缓存目标详情端点（通过MCP提供）的情况下，可使用以下启发式方法：

检查基准与目标提交之间的
```
git diff
```
，查看哪些文件发生了变更。
将变更文件映射到对应的Tuist目标/模块。
发生直接源文件变更的目标很可能是根因。
仅因依赖哈希连锁变更的目标属于次级失效。

Common root causes of cache invalidation

缓存失效的常见根因

Cause	Description
Source changes	Files in the target's source directory were modified
Resource changes	Assets, XIBs, storyboards, or other resources changed
Build settings	Target or project build settings were modified
Dependency changes	An external dependency version changed
Info.plist changes	The target's Info.plist was modified
Entitlements changes	The entitlements file was modified
Deployment target	The minimum deployment target changed
Headers	Public or project headers changed
Project settings	Shared project-level settings changed

原因	描述
源文件变更	目标源目录中的文件被修改
资源变更	资源文件、XIB、故事板或其他资源发生变更
构建设置变更	目标或项目的构建设置被修改
依赖变更	外部依赖版本发生变更
Info.plist变更	目标的Info.plist文件被修改
权限文件变更	权限文件被修改
部署目标变更	最低部署目标发生变更
头文件变更	公开或项目头文件发生变更
项目设置变更	共享项目级设置发生变更

Step 4: Assess Impact

步骤4：评估影响

Categorize the cache invalidation:

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.

对缓存失效进行分类：

预期内：源文件被有意修改，导致预期内的缓存未命中。
意外：无源代码变更但缓存失效（如构建设置、Xcode版本等原因）。
连锁反应：微小变更引发大量下游目标失效。

Summary Format

总结格式

Produce a summary with:

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

Example:

Generation Comparison: base (gen-123 on main) vs head (gen-456 on feature-x)

Duration: 12.5s -> 28.3s (+126%) -- REGRESSION
Cache hit rate: 92% (46/50) -> 64% (32/50) (-28%) -- REGRESSION
Status: success -> success

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

Cache invalidation breakdown:
- Direct changes: FoundationModule (sources changed)
- Cascade: NetworkModule, AuthModule, UIModule, + 11 others (dependency hash changed)

Recommendations:
- Consider splitting FoundationModule into smaller modules to reduce cascade impact
- The 14 cascaded targets could benefit from more granular dependency declarations
- If FoundationModule changes frequently, consider interface/implementation module splitting

生成包含以下内容的总结：

总体结论：缓存命中率提升、下降或稳定。
缓存命中率：基准命中率与目标命中率及差值。
耗时：绝对变化和百分比变化。
根因目标：哪些目标发生了直接变更。
连锁影响：因依赖连锁反应导致多少目标失效。
建议：如何减少缓存失效的方法。

示例：

生成运行对比：基准（main分支上的gen-123） vs 目标（feature-x分支上的gen-456）

耗时：12.5s -> 28.3s（+126%）-- 性能下降
缓存命中率：92%（46/50）-> 64%（32/50）（-28%）-- 性能下降
状态：成功 -> 成功

根因：FoundationModule发生源文件变更（3个文件被修改）。
这引发了依赖FoundationModule的14个下游目标失效。

缓存失效细分：
- 直接变更：FoundationModule（源文件变更）
- 连锁反应：NetworkModule、AuthModule、UIModule，以及其他11个目标（依赖哈希值变更）

建议：
- 考虑将FoundationModule拆分为更小的模块，以减少连锁影响
- 14个连锁失效目标可受益于更细粒度的依赖声明
- 若FoundationModule频繁变更，考虑采用接口/实现模块拆分方式

Done Checklist

完成检查清单

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

已解析基准和目标生成记录
已对比耗时和缓存命中率
已识别缓存失效的根因目标
已分析连锁影响
已提供减少缓存未命中的可行建议