compare-bundles

name	compare-bundles
description	Compares two app bundles to identify size changes, new or removed artifacts, and platform differences. Can be invoked with bundle IDs, dashboard URLs, or branch names.

Compare Bundles

Quick Start

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

1. Run tuist bundle list --json to find bundles on each branch.
2. Run tuist bundle show <bundle-id> --json for both base and head bundles.
3. Compare artifact trees with tuist bundle artifact list <bundle-id> --json.
4. Compare install size, download size, and other metadata.
5. Summarize size changes with actionable recommendations.

Step 1: Resolve Bundles

If base/head are bundle IDs or dashboard URLs

Fetch each directly:

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

If base/head are branch names

List recent bundles on each branch and pick the latest:

tuist bundle list --git-branch <base-branch> --json
tuist bundle list --git-branch <head-branch> --json

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

Step 2: Compare Artifact Trees

After fetching both bundles with tuist bundle show <id> --json, compare the individual artifacts:

tuist bundle artifact list <base-id> --json
tuist bundle artifact list <head-id> --json

Match artifacts by name across both bundles. Look for:

• New artifacts added in the head bundle (potential size contributors)
• Removed artifacts (explain size decreases)
• Size changes in existing artifacts

Step 3: Compare Top-Level Metrics

After fetching both bundles, compare:

Metric	What to check
install_size	Flag if head is >5% larger
download_size	Flag if head is >5% larger
version	Note version changes
supported_platforms	Note platform changes
app_bundle_id	Should match between base and head

Compute deltas:

• Install size delta: head_install_size - base_install_size
• Download size delta: head_download_size - base_download_size
• Percentage change: delta / base_size * 100

Step 4: Analyze Size Changes

If size increased significantly (>5%):

1. Check if version changed, which might explain expected size growth.
2. Check if supported_platforms changed (adding a platform increases size).
3. Look at the artifacts field in the bundle details for individual artifact sizes.

Common causes of size increases:

• New frameworks or libraries added
• Asset catalogs grew (new images, videos)
• Unoptimized resources (large PNGs instead of compressed formats)
• Debug symbols included in release builds
• New localizations added

Common causes of size decreases:

• Removed unused frameworks
• Optimized assets
• Tree shaking or dead code elimination improvements
• Moved functionality to on-demand resources

Summary Format

Produce a summary with:

1. Overall verdict: Size increased, decreased, or stable.
2. Install size: Absolute and percentage change.
3. Download size: Absolute and percentage change.
4. Version: Note if version changed.
5. Platforms: Note any platform changes.
6. Recommendations: Actionable next steps for size regressions.

Example:

Bundle Comparison: base (v2.1.0 on main) vs head (v2.2.0 on feature-x)

Install Size: 45.2 MB -> 52.8 MB (+16.8%) -- REGRESSION
Download Size: 28.1 MB -> 32.4 MB (+15.3%) -- REGRESSION
Version: 2.1.0 -> 2.2.0
Platforms: iOS, macOS (unchanged)

The install size increased by 7.6 MB. This is a significant increase
that may affect user download and storage experience.

Recommendations:
- Review new frameworks or assets added in this version
- Check for uncompressed resources or oversized image assets
- Consider using asset compression or on-demand resources
- Run `xcrun bitcode_strip` analysis to check for unnecessary bitcode

Done Checklist

• Resolved both base and head bundles
• Compared artifact trees using tuist bundle artifact list
• Compared install and download sizes
• Analyzed root causes of size changes
• Provided actionable recommendations