Merge pull request #3421 from aevesdocker/ENGDOCS-2992

docs: --load flag clarity

Author: crazy-max

commands/bake.go

@@ -499,8 +499,8 @@ func bakeCmd(dockerCli command.Cli, rootOpts *rootOptions) *cobra.Command {
 	flags := cmd.Flags()
 
 	flags.StringArrayVarP(&options.files, "file", "f", []string{}, "Build definition file")
-	flags.BoolVar(&options.exportLoad, "load", false, `Shorthand for "--set=*.output=type=docker"`)
-	flags.BoolVar(&options.exportPush, "push", false, `Shorthand for "--set=*.output=type=registry"`)
+	flags.BoolVar(&options.exportLoad, "load", false, `Shorthand for "--set=*.output=type=docker". Conditional.`)
+	flags.BoolVar(&options.exportPush, "push", false, `Shorthand for "--set=*.output=type=registry". Conditional.`)
 	flags.StringVar(&options.sbom, "sbom", "", `Shorthand for "--set=*.attest=type=sbom"`)
 	flags.StringVar(&options.provenance, "provenance", "", `Shorthand for "--set=*.attest=type=provenance"`)
 	flags.StringArrayVar(&options.overrides, "set", nil, `Override target value (e.g., "targetpattern.key=value")`)

docs/reference/buildx_bake.md

@@ -22,14 +22,14 @@ Build from a file
 | `-D`, `--debug`                     | `bool`        |         | Enable debug logging                                                                                         |
 | [`-f`](#file), [`--file`](#file)    | `stringArray` |         | Build definition file                                                                                        |
 | [`--list`](#list)                   | `string`      |         | List targets or variables                                                                                    |
-| `--load`                            | `bool`        |         | Shorthand for `--set=*.output=type=docker`                                                                   |
+| [`--load`](#load)                   | `bool`        |         | Shorthand for `--set=*.output=type=docker`. Conditional.                                                     |
 | [`--metadata-file`](#metadata-file) | `string`      |         | Write build result metadata to a file                                                                        |
 | [`--no-cache`](#no-cache)           | `bool`        |         | Do not use cache when building the image                                                                     |
 | [`--print`](#print)                 | `bool`        |         | Print the options without building                                                                           |
 | [`--progress`](#progress)           | `string`      | `auto`  | Set type of progress output (`auto`, `quiet`, `plain`, `tty`, `rawjson`). Use plain to show container output |
 | [`--provenance`](#provenance)       | `string`      |         | Shorthand for `--set=*.attest=type=provenance`                                                               |
 | [`--pull`](#pull)                   | `bool`        |         | Always attempt to pull all referenced images                                                                 |
-| `--push`                            | `bool`        |         | Shorthand for `--set=*.output=type=registry`                                                                 |
+| [`--push`](#push)                   | `bool`        |         | Shorthand for `--set=*.output=type=registry`. Conditional.                                                   |
 | [`--sbom`](#sbom)                   | `string`      |         | Shorthand for `--set=*.attest=type=sbom`                                                                     |
 | [`--set`](#set)                     | `stringArray` |         | Override target value (e.g., `targetpattern.key=value`)                                                      |
 
@@ -220,6 +220,47 @@ format. Alternatively, you can use a long-form CSV syntax and specify a
 $ docker buildx bake --list=type=targets,format=json
 ```
 
+### <a name="load"></a> Load images into Docker (--load)
+
+The `--load` flag is a convenience shorthand for adding an image export of type 
+`docker`:
+
+```console
+--load   ≈   --set=*.output=type=docker
+```
+
+However, its behavior is conditional:
+
+- If the build definition has no output defined, `--load` adds
+`type=docker`.
+- If the build definition’s outputs are `docker`, `image`, `registry`,
+`oci`, `--load` will add a `type=docker` export if one is not already present.
+- If the build definition contains `local` or `tar` outputs,
+`--load` does nothing. It will not override those outputs.
+
+For example, with the following bake file:
+
+```hcl
+target "default" {
+  output = ["type=tar,dest=hi.tar"]
+}
+```
+
+With `--load`:
+
+```console
+$ docker buildx bake --load --print
+...
+"output": [
+  { 
+    "dest": "hi.tar"
+    "type": "tar",
+   }
+]
+```
+
+The `tar` output remains unchanged.
+
 ### <a name="metadata-file"></a> Write build results metadata to a file (--metadata-file)
 
 Similar to [`buildx build --metadata-file`](buildx_build.md#metadata-file) but
@@ -339,6 +380,14 @@ Same as [`build --provenance`](buildx_build.md#provenance).
 
 Same as `build --pull`.
 
+### <a name="push"></a> Push images to a registry (--push)
+
+The `--push` flag follows the same logic as `--load`:
+
+- If no outputs are defined, it adds a `type=image,push=true` export.
+- For existing `image` outputs, it sets `push=true`.
+- If outputs are set to `local` or `tar`, it does not override them.
+
 ### <a name="sbom"></a> Create SBOM attestations (--sbom)
 
 Same as [`build --sbom`](buildx_build.md#sbom).