From 64608a79c7baf9e72708b110c50d970d3ea25f2a Mon Sep 17 00:00:00 2001 From: Milas Bowman Date: Tue, 27 Sep 2022 12:00:57 -0400 Subject: [PATCH 1/3] compose: update env file based on actual behavior There has been a LOT of work on this area in Compose recently. As part of this, we discovered that the documentation has been incorrect for some time. That is, the documented behavior has often never been indicative of reality (across both v1 and v2). We've standardized and cleaned things up, so the documentation now reflects current behavior. The Compose Spec requires similar corrections/reconciliation, but we're starting here to ensure that the more user-facing docs are in a good place. --- compose/env-file.md | 63 ++++++++++++++++++++++++++++++++------------- 1 file changed, 45 insertions(+), 18 deletions(-) diff --git a/compose/env-file.md b/compose/env-file.md index 382231c38bd0..68866a4e89a8 100644 --- a/compose/env-file.md +++ b/compose/env-file.md @@ -4,29 +4,56 @@ keywords: fig, composition, compose, docker, orchestration, environment, env fil title: Declare default environment variables in file --- -Compose supports declaring default environment variables in an environment file -named `.env` placed in the project directory. Docker Compose versions earlier than `1.28`, -load the `.env` file from the current working directory, where the command is executed, or from the -project directory if this is explicitly set with the `--project-directory` option. This -inconsistency has been addressed starting with `+v1.28` by limiting the default `.env` file path -to the project directory. You can use the `--env-file` commandline option to override the default -`.env` and specify the path to a custom environment file. +Compose supports declaring environment variables in an environment file. -The project directory is specified by the order of precedence: +## Syntax +The following syntax rules apply to environment files: -- `--project-directory` flag -- Folder of the first `--file` flag -- Current directory +- Each line represents a key-value pair. Values can optionally be quoted. + - `VAR=VAL` -> `VAL` + - `VAR="VAL"` -> `VAL` + - `VAR='VAL'` -> `VAL` +- Lines beginning with `#` are processed as comments and ignored. +- Inline comments for unquoted values must be proceeded with a space. + - `VAR=VAL # comment` -> `VAL` + - `VAR=VAL# not a comment` -> `VAL# not a comment` +- Inline comments for quoted values must follow the closing quote. + - `VAR="VAL # not a comment"` -> `VAL # not a comment` + - `VAR="VAL" # comment` -> `VAL` +- Blank lines are ignored. +- Unquoted and double-quoted (`"`) values will have [parameter expansion](#parameter-expansion) applied. +- Single-quoted (`'`) values will be used literally. + - `VAR='$OTHER'` -> `$OTHER` + - `VAR='${OTHER}'` -> `${OTHER}` +- Quotes can be escaped with `\`. + - `VAR='Let\'s go!'` -> `Let's go!` + - `VAR="{\"hello\": \"json\"}"` -> `{"hello": "json"}` +- Common shell escape sequences including `\n`, `\r`, `\t`, and `\\` are supported in double-quoted values. + - `VAR="some\tvalue"` -> `some value` + - `VAR='some\tvalue'` -> `some\tvalue` + - `VAR=some\tvalue` -> `some\tvalue` -## Syntax rules +### Parameter Expansion +Compose supports parameter expansion in environment files. +Parameter expansion is applied for unquoted and double-quoted values. +Both braced (`${VAR}`) and unbraced (`$VAR`) expressions are supported. -The following syntax rules apply to the `.env` file: +For braced expressions, the following formats are supported: +- Direct substitution + - `${VAR}` -> value of `VAR` +- Default value + - `${VAR:-default}` -> value of `VAR` if set and non-empty, otherwise `default` + - `${VAR-default}` -> value of `VAR` if set, otherwise `default` +- Required value + - `${VAR:?error}` -> value of `VAR` if set and non-empty, otherwise exit with error + - `${VAR?error}` -> value of `VAR` if set, otherwise exit with error +- Alternative value + - `${VAR:+replacement}` -> `replacement` if `VAR` is set and non-empty, otherwise empty + - `${VAR+replacement}` -> `replacement` if `VAR` is set, otherwise empty -- Compose expects each line in an `env` file to be in `VAR=VAL` format. -- Lines beginning with `#` are processed as comments and ignored. -- Blank lines are ignored. -- There is no special handling of quotation marks. This means that - **they are part of the VAL**. +## Precedence +Environment variables from an environment file have lower precedence than those passed via the command-line or via the `environment` section in project YAML. +Refer to [Environment Variables Precedence](./envvars-precedence.md) for details. ## Compose file and CLI variables From 19ed754e03aa09588ecb4d6aa6293f8fe03239a5 Mon Sep 17 00:00:00 2001 From: Allie Sadler <102604716+aevesdocker@users.noreply.github.com> Date: Wed, 28 Sep 2022 09:25:36 +0100 Subject: [PATCH 2/3] Update compose/env-file.md --- compose/env-file.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/compose/env-file.md b/compose/env-file.md index 68866a4e89a8..0c7e44567eed 100644 --- a/compose/env-file.md +++ b/compose/env-file.md @@ -22,7 +22,7 @@ The following syntax rules apply to environment files: - `VAR="VAL" # comment` -> `VAL` - Blank lines are ignored. - Unquoted and double-quoted (`"`) values will have [parameter expansion](#parameter-expansion) applied. -- Single-quoted (`'`) values will be used literally. +- Single-quoted (`'`) values are used literally. - `VAR='$OTHER'` -> `$OTHER` - `VAR='${OTHER}'` -> `${OTHER}` - Quotes can be escaped with `\`. From 517ff23648103df660c244bad034643bbf3e62e9 Mon Sep 17 00:00:00 2001 From: Allie Sadler <102604716+aevesdocker@users.noreply.github.com> Date: Wed, 28 Sep 2022 09:25:44 +0100 Subject: [PATCH 3/3] Update compose/env-file.md --- compose/env-file.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/compose/env-file.md b/compose/env-file.md index 0c7e44567eed..599411742ee4 100644 --- a/compose/env-file.md +++ b/compose/env-file.md @@ -21,7 +21,7 @@ The following syntax rules apply to environment files: - `VAR="VAL # not a comment"` -> `VAL # not a comment` - `VAR="VAL" # comment` -> `VAL` - Blank lines are ignored. -- Unquoted and double-quoted (`"`) values will have [parameter expansion](#parameter-expansion) applied. +- Unquoted and double-quoted (`"`) values have [parameter expansion](#parameter-expansion) applied. - Single-quoted (`'`) values are used literally. - `VAR='$OTHER'` -> `$OTHER` - `VAR='${OTHER}'` -> `${OTHER}`