Implementation:

• API client: client.ImagePush(): default to ":latest" instead of "all tags" moby/moby#40302 client.ImagePush(): default to ":latest" instead of "all tags"
• CLI: implement docker push -a/--all-tags #2220 implement docker push -a/--all-tags
• docs: (no PR yet)

The docker push command up until v0.9.1 always pushed all tags of a given image, so docker push foo/bar would push (e.g.) all of foo/bar:latest, foo:/bar:v1, foo/bar:v1.0.0.

Pushing all tags of an image was not desirable in many case, so docker v0.10.0 enhanced docker push to optionally specify a tag to push (docker push foo/bar:v1) (see moby/moby#3411 and the pull request that implemented this: moby/moby#4948).

This behavior exists up until today, and is confusing, because unlike other commands, docker push does not default to use the :latest tag when omitted, but instead makes it push "all tags of the image"

For example, in the following situation;

docker images

REPOSITORY          TAG                        IMAGE ID            CREATED             SIZE
thajeztah/myimage   latest                     b534869c81f0        41 hours ago        1.22MB

Running docker push thajeztah/myimage seemingly does the expected behavior (it pushes thajeztah/myimage:latest to Docker Hub), however, it does not so for the reason expected (:latest being the default tag), but because :latest happens to be the only tag present for the thajeztah/myimage image.

If another tag exists for the image:

docker images

REPOSITORY          TAG                        IMAGE ID            CREATED             SIZE
thajeztah/myimage   latest                     b534869c81f0        41 hours ago        1.22MB
thajeztah/myimage   v1.0.0                     b534869c81f0        41 hours ago        1.22MB

Running the same command (docker push thajeztah/myimage) will push both images to Docker Hub.

Note that the behavior described above is currently not (clearly) documented; the docker push reference documentation (https://docs.docker.com/engine/reference/commandline/push/) does not mention that omitting the tag will push all tags

Proposed change

First of all, it should be noted that changing this behavior will be a breaking change, so should be clearly mentioned in the release notes.

I think changing the behavior should be reversed, and a flag should be added to opt-in to the behavior:

• docker push myname/myimage will be the equivalent of docker push myname/myimage:latest
• to push all images, the user needs to set a flag (e.g. --all-tags), so docker push --all-tags myname/myimage:latest

Alternatively, we can add support for pushing multiple tags to docker push. There is still discussion around this, as pushing multiple images or multiple tags should be optimised (instead of just looping through the provided tags). There's also a (slightly related) proposal to specify a source image on push; moby/moby#38880. That proposal was put on hold until the containerd integration was completed.