Documentation doesn't include `FROM <image>:tag@digest`

[pnacht]

Is this a docs issue?

• [X] My issue is about the documentation content or website

Type of issue

I can't find what I'm looking for

Description

The FROM documentation currently describes three possible syntaxes:

FROM [--platform=<platform>] <image> [AS <name>] Or FROM [--platform=<platform>] <image>[:<tag>] [AS <name>] Or FROM [--platform=<platform>] <image>[@<digest>] [AS <name>]

However, there is another possibility:

FROM [--platform=<platform>] <image>[:<tag>][@<digest>] [AS <name>]

For example:

FROM ubuntu:jammy@sha256:1a2b3c... AS foo

An image may be pinned to both a tag and a digest at the same time. In such cases, the tag is completely ignored by Docker and only the digest is taken into account.

However, the tag is still useful for added human legibility and can be used by automated tools such as dependabot to help them understand how they should update the image.

Location

https://docs.docker.com/engine/reference/builder/#from

Suggestion

Add something like the description given above to the documentation.

Alternatively, combine the two "pin cases" into one, since they both use the [optional] syntax anyway:

FROM [--platform=<platform>] <image>[:<tag>][@digest] [AS <name>]

And then the final bullet point that describes them can become

The tag or digest values are optional. If you omit both, the builder assumes a latest tag by default. If you include both, the digest takes precedence and the tag is ignored, but can still be useful for human-legibility and to aid automated update tools. The builder returns an error if it cannot find the tag value.

[docker-robot[bot]]

There hasn't been any activity on this issue for a long time. If the problem is still relevant, mark the issue as fresh with a /remove-lifecycle stale comment. If not, this issue will be closed in 14 days. This helps our maintainers focus on the active issues.

Prevent issues from auto-closing with a /lifecycle frozen comment.

/lifecycle stale

[pnacht]

/remove-lifecycle stale