Merge pull request #23794 from dvdksn/buildx-platform-split

build: improve platform-split exporter opt description

Author: dvdksn

content/manuals/build/exporters/local-tar.md

@@ -25,10 +25,109 @@ $ docker buildx build --output type=tar[,parameters] .
 
 The following table describes the available parameters:
 
-| Parameter        | Type    | Default | Description                                                                                                                                                                                                                            |
-|------------------|---------|---------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `dest`           | String  |         | Path to copy files to                                                                                                                                                                                                                  |
-| `platform-split` | Boolean | `true`  | When using the local exporter with a multi-platform build, by default, a subfolder matching each target platform is created in the destination directory. Set it to `false` to merge files from all platforms into the same directory. |
+| Parameter        | Type    | Default | Description                                                                       |
+| ---------------- | ------- | ------- | --------------------------------------------------------------------------------- |
+| `dest`           | String  |         | Path to copy files to                                                             |
+| `platform-split` | Boolean | `true`  | `local` exporter only. Split multi-platform outputs into platform subdirectories. |
+
+## Multi-platform builds with local exporter
+
+The `platform-split` parameter controls how multi-platform build outputs are
+organized.
+
+Consider this Dockerfile that creates platform-specific files:
+
+```dockerfile
+FROM busybox AS build
+ARG TARGETOS
+ARG TARGETARCH
+RUN mkdir /out && echo foo > /out/hello-$TARGETOS-$TARGETARCH
+
+FROM scratch
+COPY --from=build /out /
+```
+
+### Split by platform (default)
+
+By default, the local exporter creates a separate subdirectory for each
+platform:
+
+```console
+$ docker buildx build \
+  --platform linux/amd64,linux/arm64 \
+  --output type=local,dest=./output \
+  .
+```
+
+This produces the following directory structure:
+
+```text
+output/
+├── linux_amd64/
+│   └── hello-linux-amd64
+└── linux_arm64/
+    └── hello-linux-arm64
+```
+
+### Merge all platforms
+
+To merge files from all platforms into the same directory, set
+`platform-split=false`:
+
+```console
+$ docker buildx build \
+  --platform linux/amd64,linux/arm64 \
+  --output type=local,dest=./output,platform-split=false \
+  .
+```
+
+This produces a flat directory structure:
+
+```text
+output/
+├── hello-linux-amd64
+└── hello-linux-arm64
+```
+
+Files from all platforms merge into a single directory. If multiple platforms
+produce files with identical names, the export fails with an error.
+
+### Single-platform builds
+
+Single-platform builds export directly to the destination directory without
+creating a platform subdirectory:
+
+```console
+$ docker buildx build \
+  --platform linux/amd64 \
+  --output type=local,dest=./output \
+  .
+```
+
+This produces:
+
+```text
+output/
+└── hello-linux-amd64
+```
+
+To include the platform subdirectory even for single-platform builds, explicitly
+set `platform-split=true`:
+
+```console
+$ docker buildx build \
+  --platform linux/amd64 \
+  --output type=local,dest=./output,platform-split=true \
+  .
+```
+
+This produces:
+
+```text
+output/
+└── linux_amd64/
+    └── hello-linux-amd64
+```
 
 ## Further reading