Incomplete and misleading description of .env file syntax regarding multiline values

[jest]

Is this a docs issue?

• My issue is about the documentation content or website

Type of issue

Information is incorrect

Description

The current documentation of .env file syntax overlooks the existence of multi-line values. This omission not only makes the documentation incomplete, but also misleading in how it describes potential .env file parsing.

Example

Given the following files:

.env:

KEY='SOME
VALUE'

compose.yml

name: p
services:
  some:
    image: anything
    environment:
      KEY: ${KEY}

running the command:

$ docker compose config

produces:

name: p
services:
  some:
    environment:
      KEY: |-
        SOME
        VALUE
    image: anything
    networks:
      default: null
networks:
  default:
    name: p_default

Clearly, multi-line strings are supported—either as actual newlines within quotes, as shown above, or via escaped newlines (e.g., quoted \n).

However, the current documentation presents a simplified view of .env parsing, implying a naive "one line = one variable" approach. For example, from the documentation (https://github.com/docker/docs/blob/main/content/manuals/compose/how-tos/environment-variables/variable-interpolation.md#env-file-syntax):

The following syntax rules apply to environment files:

• Lines beginning with # are processed as comments and ignored.
• Blank lines are ignored.
• Unquoted and double-quoted (") values have interpolation applied.
• Each line represents a key-value pair. Values can optionally be quoted.

If this is to be treated as a specification, it strongly encourages writing overly simplistic parsers that are incapable of handling valid .env files—something I experienced first-hand when ChatGPT followed the spec too literally 😄.

Location

https://docs.docker.com/compose/how-tos/environment-variables/variable-interpolation/#env-file-syntax

Suggestion

The linked documentation should be updated to reflect the actual behavior of .env parsing in Docker Compose, including proper handling of multi-line values and quoting nuances. This should prevent incorrect assumptions and promote more robust tooling.