COPY --link example uses incorrect # syntax directive

[thernstig]

Is this a docs issue?

• My issue is about the documentation content or website

Type of issue

Information is incorrect

Description

https://docs.docker.com/engine/reference/builder/#copy---link states:

Added in docker/dockerfile:1.4

But then it goes to show:

# syntax=docker/dockerfile:1
FROM alpine
COPY --link /foo /bar

Which clearly uses # syntax=docker/dockerfile:1.

Location

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

Suggestion

Change the example to use # syntax=docker/dockerfile:4

[thernstig]

How does one even know what # syntax=docker/dockerfile:1 is used if non is specified in the Dockerfile? I.e. how do I know what the default is for my version of Docker (buildx/Engine/CLI or wherever the default comes from).

[dvdksn]

hi, thanks for raising the issue/question

The docker/dockerfile:1 syntax directive forces BuildKit to use the latest stable version of the Dockerfile syntax, by fetching the latest version of the syntax parser from Docker Hub. https://hub.docker.com/r/docker/dockerfile

The 1 tag represents the "latest v1.x version", which is currently 1.6, meaning it includes features introduced in 1.4 like the COPY --link flag.

If the syntax directive is unspecified, BuildKit uses whatever Dockerfile syntax you have bundled with your local BuildKit version. To see which version of BuildKit you're running locally, you can use the docker buildx ls command.

We mention this in a few different places of the documentation, although not in the Dockerfile reference itself. See here for example: https://docs.docker.com/build/building/packaging/#dockerfile-syntax

It seems like we could improve the section on the syntax directive in the Dockerfile reference itself, or at least add a link to the relevant section where it's described in more detail. Let me look into it.

[dvdksn]

Fixed in moby/buildkit#4519 - will be updated in docs in the near future

[docker-robot]

Closed issues are locked after 30 days of inactivity.
This helps our team focus on active issues.

If you have found a problem that seems similar to this, please open a new issue.

/lifecycle locked