[CHE3MZ]

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update

Motivation and Context

container image pull without --platform unpacks a snapshot for every architecture in the image index, while run unpacks only the requested platform via getCreateSnapshot (related: #784, #2165). Each snapshot is much smaller since containerization#924, but a multi-arch image still pays the per-architecture multiplier: alpine:latest creates a snapshot and repeats the unpack work for every platform in the index, although only one will run.

This change unpacks only the resolved platform. If --platform, --os, --arch, or CONTAINER_DEFAULT_PLATFORM is provided, that platform is used; otherwise the host platform is used. Blob fetching is unchanged, so images remain usable offline. --platform all restores the previous unpack-every-platform behavior, and other platforms are still unpacked on demand by run --platform.

Using the existing --platform option instead of a separate --all-platforms flag keeps one way to select platforms. --platform all is mutually exclusive with --os and --arch.

Testing

• Added/updated tests (Tests/ContainerCommandsTests/ImagePullPlatformTests.swift): default host, explicit platform, environment default, all, case-insensitive all, and conflicting flags.
• Added/updated docs (docs/command-reference.md).
• Tested locally on macOS with the full runtime (not yet run by the author)
• Community verification on an M-series Mac (macOS 27, main 31e3a98 + this PR): alpine:latest and postgres:18 each unpacked a single linux/arm64 snapshot, and containers started and ran normally.

Functional testing compares snapshot counts, since containerization#924 already reduced allocated bytes per snapshot. The remaining win is one snapshot and one unpack pass instead of one per architecture.

[lucasbrito-wdt]

Tested ef55fd7 on an M-series Mac (macOS 27), built from main 31e3a98 with this PR merged (plus #2380, which doesn't touch pull), using a fresh --app-root and without CONTAINER_DEFAULT_PLATFORM set.

• container image pull alpine:latest and postgres:18 each unpacked a single linux/arm64 snapshot. On 1.5.0 the same pulls unpack one snapshot per platform in the index ([Bug]: A pull with no --platform unpacks an ext4 snapshot for every platform in the index #2165).
• The containers still start and run normally from the arm64 snapshot.

For anyone measuring disk usage while testing this: on main the snapshots are also much smaller (alpine 41 MB allocated vs 1.09 GB on 1.5.0). That comes from the journal fix in containerization#924, not from this PR.

[CHE3MZ]

Thanks for testing this on current main — that's the confirmation the PR needed, and the note about containerization#924 is important. I've rebased on 31e3a98 and reworked the flag: instead of a separate --all-platforms (which quietly did the wrong thing when CONTAINER_DEFAULT_PLATFORM was set), the existing --platform option now accepts �ll. Default pulls unpack only the resolved platform; all blobs are still fetched, and other platforms unpack on demand. I also corrected the PR's disk figures, since #924 makes per-snapshot allocation much smaller than the 1.5.0 numbers originally quoted.