docker buildx --help: misleading example for the value of --tag

[gjvc]

Description

the docker buildx help output is misleading for the value of --tag. Strictly speaking, a tag is what comes after the colon, like "latest" or "20250819.1234".

In practice, one ends up passing the complete image name to "--tag", which is extremely confusing for people starting to use the tool for the first time. (I have had to explain this to many people and correct their understanding that

image == {registry}{repository}:{tag}

instead of creating a new option, improving the help text might be the easiest and most helpful thing to do. "name" is an ambiguous term, "repository:tag", or "[registry/]repository[:tag]" are more informative to help new users join the dots.

Reproduce

docker buildx --help

should emit
...
-t, --tag stringArray Image identifier (format: "repository:tag")
or
-t, --tag stringArray Image identifier (format: "[registry/]repository[:tag]")
...

instead of
...
-t, --tag stringArray Name and optionally a tag (format: "name:tag")
...

Expected behavior

...
-t, --tag stringArray Image identifier (format: "[registry/]repository[:tag]")
...

docker version

> docker version
Client: Docker Engine - Community
 Version:           28.3.3
 API version:       1.51
 Go version:        go1.24.5
 Git commit:        980b856
 Built:             Fri Jul 25 11:36:28 2025
 OS/Arch:           linux/amd64
 Context:           default

Server: Docker Engine - Community
 Engine:
  Version:          28.3.3
  API version:      1.51 (minimum version 1.24)
  Go version:       go1.24.5
  Git commit:       bea959c
  Built:            Fri Jul 25 11:33:28 2025
  OS/Arch:          linux/amd64
  Experimental:     false
 containerd:
  Version:          1.7.27
  GitCommit:        05044ec0a9a75232cad458027ca83437aae3f4da
 runc:
  Version:          1.2.5
  GitCommit:        v1.2.5-0-g59923ef
 docker-init:
  Version:          0.19.0
  GitCommit:        de40ad0

docker info

> docker info
Client: Docker Engine - Community
 Version:    28.3.3
 Context:    default
 Debug Mode: false
 Plugins:
  buildx: Docker Buildx (Docker Inc.)
    Version:  v0.26.1
    Path:     /usr/libexec/docker/cli-plugins/docker-buildx
  compose: Docker Compose (Docker Inc.)
    Version:  v2.39.1
    Path:     /usr/libexec/docker/cli-plugins/docker-compose

Server:
 Containers: 11
  Running: 0
  Paused: 0
  Stopped: 11
 Images: 11
 Server Version: 28.3.3
 Storage Driver: overlay2
  Backing Filesystem: extfs
  Supports d_type: true
  Using metacopy: false
  Native Overlay Diff: true
  userxattr: false
 Logging Driver: json-file
 Cgroup Driver: systemd
 Cgroup Version: 2
 Plugins:
  Volume: local
  Network: bridge host ipvlan macvlan null overlay
  Log: awslogs fluentd gcplogs gelf journald json-file local splunk syslog
 CDI spec directories:
  /etc/cdi
  /var/run/cdi
 Swarm: inactive
 Runtimes: io.containerd.runc.v2 runc
 Default Runtime: runc
 Init Binary: docker-init
 containerd version: 05044ec0a9a75232cad458027ca83437aae3f4da
 runc version: v1.2.5-0-g59923ef
 init version: de40ad0
 Security Options:
  seccomp
   Profile: builtin
  cgroupns
 Kernel Version: 5.14.0-570.24.1.el9_6.x86_64
 Operating System: Red Hat Enterprise Linux 9.6 (Plow)
 OSType: linux
 Architecture: x86_64
 CPUs: 48
 Total Memory: 125GiB
 Name: nyc01prog07.mf.iontrading.net
 ID: dc6c3225-2e43-4e7c-9fc7-f5aeda907481
 Docker Root Dir: /var/lib/docker
 Debug Mode: false
 Experimental: false
 Insecure Registries:
  ::1/128
  127.0.0.0/8
 Live Restore Enabled: false

Additional Info

No response