compare-bundles

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