Compare Bundles
Quick Start
You'll typically receive two bundle identifiers. Follow these steps:
- Run
tuist bundle list --jsonto find bundles on each branch. - Run
tuist bundle show <bundle-id> --jsonfor both base and head bundles. - Compare artifact trees with
tuist bundle artifact list <bundle-id> --json. - Compare install size, download size, and other metadata.
- 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> --jsonIf 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> --jsonThen 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> --jsonMatch 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%):
- Check if
versionchanged, which might explain expected size growth. - Check if
supported_platformschanged (adding a platform increases size). - Look at the
artifactsfield 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:
- Overall verdict: Size increased, decreased, or stable.
- Install size: Absolute and percentage change.
- Download size: Absolute and percentage change.
- Version: Note if version changed.
- Platforms: Note any platform changes.
- 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 bitcodeDone 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