compare-gradle-builds

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Compare Gradle Builds

对比Gradle构建

Quick Start

快速开始

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

Use
```
list_gradle_builds
```
to find builds on each branch.
Use
```
get_gradle_build
```
for both base and head builds.
Use
```
list_gradle_build_tasks
```
to fetch task-level details for both builds.
Compare duration, status, cache hit rates, and task outcomes.
Summarize regressions, improvements, and recommendations.

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

你通常会收到两个构建标识符（ID、仪表板URL或分支名称）。使用Tuist MCP工具按照以下步骤操作：

使用
```
list_gradle_builds
```
查找各分支上的构建。
对基准构建（base）和目标构建（head）分别使用
```
get_gradle_build
```
。
使用
```
list_gradle_build_tasks
```
获取两个构建的任务级详细信息。
对比时长、状态、缓存命中率和任务结果。
总结退化点、改进点及建议。

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

Step 1: Resolve Builds

步骤1：解析构建

If base/head are build IDs or dashboard URLs

若基准/目标为构建ID或仪表板URL

Fetch each directly with

get_gradle_build(build_run_id: "<id>")

直接使用

get_gradle_build(build_run_id: "<id>")

获取每个构建。

If base/head are branch names

若基准/目标为分支名称

List recent builds on each branch and pick the latest:

list_gradle_builds(account_handle: "...", project_handle: "...", git_branch: "<branch>", page_size: 1)

Then fetch full details with

get_gradle_build(build_run_id: "<id>")

列出各分支上的近期构建并选择最新的一个：

list_gradle_builds(account_handle: "...", project_handle: "...", git_branch: "<branch>", page_size: 1)

然后使用

get_gradle_build(build_run_id: "<id>")

获取完整详情。

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: Compare Top-Level Metrics

步骤2：对比顶层指标

After fetching both builds, compare:

Metric	What to check
`duration_ms`	Flag if head is >10% slower than base
`status`	Flag if base succeeded but head failed
`tasks_local_hit_count`	Compare local cache hit counts
`tasks_remote_hit_count`	Compare remote cache hit counts
`tasks_executed_count`	Compare how many tasks ran (higher means more cache misses)
`cacheable_tasks_count`	Note if the cacheable task count changed
`cache_hit_rate`	`(local_hits + remote_hits) / cacheable_tasks_count * 100`
`requested_tasks`	Ensure both builds ran the same tasks for a fair comparison
`gradle_version` / `java_version`	Note environment differences that affect comparability

Compute the cache miss delta:

base_executed - head_executed

. Positive means head has fewer executions (improvement). Negative means regression.

获取两个构建后，对比以下内容：

指标	检查要点
`duration_ms`	若目标构建比基准构建慢10%以上则标记
`status`	若基准构建成功但目标构建失败则标记
`tasks_local_hit_count`	对比本地缓存命中次数
`tasks_remote_hit_count`	对比远程缓存命中次数
`tasks_executed_count`	对比运行的任务数量（数值越高表示缓存未命中越多）
`cacheable_tasks_count`	记录可缓存任务数量是否有变化
`cache_hit_rate`	计算公式： `(本地命中数 + 远程命中数) / 可缓存任务数 * 100`
`requested_tasks`	确保两个构建运行相同的任务以保证对比公平
`gradle_version` / `java_version`	记录影响可比性的环境差异

计算缓存未命中差值：

基准执行数 - 目标执行数

。正数表示目标构建执行任务更少（有改进），负数表示出现退化。

Step 3: Drill Into Tasks

步骤3：深入分析任务

Use

list_gradle_build_tasks

for both builds. Compare

duration_ms

and

outcome

per task path.

Look for:

Tasks that changed from
```
local_hit
```
or
```
remote_hit
```
to
```
executed
```
(cache invalidation).
Tasks that changed from
```
executed
```
to
```
local_hit
```
or
```
remote_hit
```
(cache improvement).
Tasks that changed to
```
failed
```
(new failures).
New tasks that appeared in the head build.
Tasks with significant duration increases.

Sort by absolute time difference to find the biggest regressions.

对两个构建使用

list_gradle_build_tasks

。按任务路径对比

duration_ms

和

outcome

。

重点关注：

从
```
local_hit
```
或
```
remote_hit
```
变为
```
executed
```
的任务（缓存失效）。
从
```
executed
```
变为
```
local_hit
```
或
```
remote_hit
```
的任务（缓存优化）。
变为
```
failed
```
的任务（新失败项）。
目标构建中新增的任务。
时长显著增加的任务。

按绝对时间差排序，找出最严重的退化项。

Filtering tasks

任务过滤

Use the

outcome

filter to focus on specific task states:

list_gradle_build_tasks(build_run_id: "<id>", outcome: "executed")

to see only executed tasks.

list_gradle_build_tasks(build_run_id: "<id>", outcome: "failed")

to see failures.

list_gradle_build_tasks(build_run_id: "<id>", cacheable: true)

to see only cacheable tasks.

使用

outcome

过滤器聚焦特定任务状态：

list_gradle_build_tasks(build_run_id: "<id>", outcome: "executed")

查看仅执行的任务。

list_gradle_build_tasks(build_run_id: "<id>", outcome: "failed")

查看失败任务。

list_gradle_build_tasks(build_run_id: "<id>", cacheable: true)

查看仅可缓存任务。

Step 4: Investigate Duration Regressions

步骤4：调查时长退化

If the head build is significantly slower:

Check if
```
requested_tasks
```
differ (different task sets are not directly comparable).
Check if cache hit rate dropped, which would explain longer builds.
Look for tasks that changed from cache hits to
```
executed
```
.
Check if
```
gradle_version
```
or
```
java_version
```
changed, which can affect performance.
Compare individual task durations to find the biggest contributors.

若目标构建明显变慢：

检查
```
requested_tasks
```
是否不同（不同任务集无法直接对比）。
检查缓存命中率是否下降，这可能是构建时长增加的原因。
查找从缓存命中变为
```
executed
```
的任务。
检查
```
gradle_version
```
或
```
java_version
```
是否变更，这会影响性能。
对比单个任务的时长，找出最大影响因素。

Step 5: Investigate Cache Changes

步骤5：调查缓存变化

Compare task-level cache behavior:

Hit rate dropped: Possible causes include dependency changes, build configuration changes, or Gradle version updates that alter cache keys.
Hit rate improved: Likely due to better cache warming or fewer source changes.
Task count changed: New modules or tasks added/removed.
Outcome changes: Tasks moving between
```
up_to_date
```
,
```
local_hit
```
,
```
remote_hit
```
, and
```
executed
```
reveal cache effectiveness.

对比任务级缓存行为：

命中率下降：可能原因包括依赖变更、构建配置变更或Gradle版本更新导致缓存键改变。
命中率提升：可能是由于缓存预热更充分或源代码变更更少。
任务数量变化：新增或移除了模块或任务。
结果变化：任务在
```
up_to_date
```
、
```
local_hit
```
、
```
remote_hit
```
和
```
executed
```
之间的转换反映了缓存的有效性。

Step 6: Check Build Context

步骤6：检查构建上下文

Compare environment details:

```
gradle_version
```
and
```
java_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.
```
root_project_name
```
: Ensure both builds are from the same project structure.

对比环境详情：

```
gradle_version
```
和
```
java_version
```
：不同版本会影响构建时长和缓存有效性。
```
is_ci
```
：CI构建与本地构建的性能特征可能不同。
```
git_branch
```
和
```
git_commit_sha
```
：验证构建是否来自预期的提交。
```
root_project_name
```
：确保两个构建来自相同的项目结构。

Summary Format

总结格式

Produce a summary with:

Overall verdict: Better, worse, or neutral compared to base.
Duration: Absolute and percentage change in
```
duration_ms
```
.
Cache hit rate: Change in hit rate with explanation.
Task outcomes: Notable outcome changes (hit to executed, new failures).
Status: Any status changes (success to failure 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: 45200ms -> 62800ms (+39%) -- REGRESSION
Cache hit rate: 85% -> 72% (-13%) -- 8 tasks went from cache hit to executed
Status: success -> success

Root cause: Cache hit rate dropped because 8 tasks had invalidated caches.
The :app:compileKotlin task changed from remote_hit to executed,
cascading to 7 downstream tasks.

Recommendations:
- Investigate which source changes invalidated :app:compileKotlin cache
- Consider splitting large modules to reduce cache invalidation cascading

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

整体结论：与基准构建相比更好、更差或无变化。
时长：
```
duration_ms
```
的绝对变化和百分比变化。
缓存命中率：命中率变化及原因说明。
任务结果：值得注意的结果变化（从命中变为执行、新失败项等）。
状态：任何状态变化（从成功到失败或反之）。
环境：记录影响可比性的环境差异。
建议：基于发现的可操作后续步骤。

示例：

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

Duration: 45200ms -> 62800ms (+39%) -- REGRESSION
Cache hit rate: 85% -> 72% (-13%) -- 8 tasks went from cache hit to executed
Status: success -> success

Root cause: Cache hit rate dropped because 8 tasks had invalidated caches.
The :app:compileKotlin task changed from remote_hit to executed,
cascading to 7 downstream tasks.

Recommendations:
- Investigate which source changes invalidated :app:compileKotlin cache
- Consider splitting large modules to reduce cache invalidation cascading

Done Checklist

完成检查清单

Resolved both base and head builds
Compared duration, cache, and status metrics
Drilled into task-level outcomes for both builds
Identified root causes for any regressions
Provided actionable recommendations

已解析基准和目标构建
已对比时长、缓存和状态指标
已深入分析两个构建的任务级结果
已识别任何退化的根本原因
已提供可操作的建议