Docker documentation erroneously claims Here-Documents being a Docker feature – they are a shell feature instead

[SetTrend]

Is this a docs issue?

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

Type of issue

Information is incorrect

Description

The Docker documentation claims that Here-Documents are a Docker feature that may be used with every shell.

However, Here-Documents do not work with Windows cmd or PowerShell.

Location

https://docs.docker.com/reference/dockerfile/#here-documents

Suggestion

It should be explicitly mentioned in the documentation that Here-Documents are a shell feature that is only available to shells supporting this feature and it's just coincidentally available to the Dockerfile RUN instruction due to the shell supporting this feature.

[dvdksn]

This section refers to heredocs in Dockerfiles, and has nothing to do with shells. It refers to BuildKit's ability to interpret multi-line RUN and COPY instructions by using heredoc delimiters for those instructions, as shown in the examples.

Are you observing some kind of issue with heredocs in Dockerfiles?

[SetTrend]

Yet, apparently, the Here-Document is interpreted by the shell, not by the Dockerfile:

When I'm using this Dockerfile:

# escape=`
FROM mcr.microsoft.com/windows/servercore:20H2
RUN <<EOT
  ECHO.
EOT

… I'm getting this build output:

Sending build context to Docker daemon ...
Step 1/2 : FROM mcr.microsoft.com/windows/servercore:20H2
 ---> d7c03b5bcc73
Step 2/2 : RUN <<EOT
 ---> Running in 1e07112fa6d9
<< was unexpected at this time.
The command 'cmd /S /C <<EOT' returned a non-zero code: 1

[dvdksn]

@tonistiigi is this working as intended? I would've thought that the heredocs for RUN are shell-agnostic, but looks like they aren't. Do Windows shells have an alternative syntax, e.g. PowerShell here-strings? https://devblogs.microsoft.com/scripting/powertip-use-here-strings-with-powershell/