Clarify image name nomenclature: what exactly is a 'tag'?

[macdjord]

Given an image called foo:8080/bar:baz:

• Some parts of the Docker documentation use the term 'tag' to mean the whole thing, while others use it to mean just the :baz part
• Some parts of the Docker documentation use the term 'repository' to mean foo:8080/bar, but the documentation for docker tag claims that the repository is actually just foo:8080, and bar is the 'name part'

This makes some parts of the documentation confusing, particularly surrounding docker rmi and docker image prune.

The documentation should be updated to:

• Establish a clear convention on what the various parts of an image identifier are called, as well as the identifier as a whole (and don't forget to cover identifiers using digests)
• Add a page which explicitly documents this convention
• Ensure said convention is followed consistently everywhere (including in the output of the docker commands)

[ndeloof]

For legacy reason those terms have been (mis)used in many ways. Nomenclature is clarified by https://github.com/opencontainers/distribution-spec/blob/main/spec.md#definitions

For backward compatibility, docker tag command still used a non-strict vocabulary, i.e. one pass a full image ID (registry/name:tag) not just a tag.

[macdjord]

@ndeloof If such a clear definition exists, it should be documented on docs.docker.com. (Though I'm not sure if that definition counts as clear; I've read it twice and, while it clearly defines 'tag' to mean just the :baz part, I still can't figure out what the proper name for the whole identifier is supposed to be.)

I recognize that renaming the docker tag command itself it impractical, but that's no excuse not to have the documentation be consistent in its terminology. For instance, there are many parts of the documentation that refer to 'untagged imaged' or 'removing a tag from an image' when they are actually talking about full identifiers, not just tags.

[ndeloof]

there are many parts of the documentation that refer to 'untagged imaged' or 'removing a tag from an image' when they are actually talking about full identifiers, not just tags.

actually, 'untagged images' is valid, to distinguish image referred by ID or digest vs tagged images. Same as 'removing a tag from an image', this deletes the tag but the image might still exists and be accessed by digest (until garbage collected). No simple way to express this in both a strict and user-friendly way ¯_(ツ)_//¯ if you have any concrete proposal to improve the docs, feel free to contribute: https://github.com/docker/docker.github.io

[macdjord]

@ndeloof: My suggestion: Pick some particular term other than 'tag' to mean the whole identifier - i.e. foo:8080/bar:baz or foo:8080/bar@sha256:000000000000 - and then go over the documentation and replace all instances of 'tag' that don't refer to an actual tag (i.e. just the :baz part) with this new term.

[thaJeztah]

Yeah, it's a tricky one, also because what users often refer to as an "image" effectively is a "repository", but "repository" is quite an overloaded term in itself.