[proposal] change "docker push" behavior to default to ":latest" instead of "all tags"

[thaJeztah]

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.

[thaJeztah]

@silvin-lubecki @tianon @dmcgowan PTAL

[thaJeztah]

/cc @nebuk89

[rokcarl]

I was burnt by the current functionality today.

I had a Makefile with:

• apush target that does docker push company/app,
• a push-production target that does docker push company/app:production.

I was under the impression that production will never be overwritten unknowingly by a developer, even if they circumvent make and just do docker push.

But then we noticed the production instance running my development code. I was like "no way!" It took me quite a while to figure out how my code ended up on production.

Additionally, there's no great solution right now for me because our production system isn't ready yet to handle running immutable tags, e.g. the ones from the git-sha, which we compile as well. This means we need to run a hard-coded tag, which is production, but a developer could wreak havoc if they ran docker push company/app.

[tianon]

I'm +1 to bringing docker push back into symmetry with docker pull: 🎉

$ docker pull --help

Usage:	docker pull [OPTIONS] NAME[:TAG|@DIGEST]

Pull an image or a repository from a registry

Options:
  -a, --all-tags                Download all tagged images in the repository
      --disable-content-trust   Skip image verification (default true)

(This was swapped for docker pull in moby/moby#7759 👍)