clarify support for PWD/.env vs project_dir/.env (#20203)

Signed-off-by: Nicolas De Loof <nicolas.deloof@gmail.com>

content/compose/environment-variables/variable-interpolation.md

@@ -60,7 +60,7 @@ Docker Compose can interpolate variables into your Compose file from multiple so
 
 ### `.env` file
 
-An `.env` file in Docker Compose is a text file used to define variables that should be made available to Docker containers when running `docker compose up`. This file typically contains key-value pairs of variables, and it lets you  centralize and manage configuration in one place. The `.env` file is useful if you have multiple variables you need to store.
+An `.env` file in Docker Compose is a text file used to define variables that should be made available for interpolation when running `docker compose up`. This file typically contains key-value pairs of variables, and it lets you  centralize and manage configuration in one place. The `.env` file is useful if you have multiple variables you need to store.
 
 The `.env` file is the default method for setting variables. The `.env` file should be placed at the root of the project directory next to your `compose.yaml` file. For more information on formatting an environment file, see [Syntax for environment files](#env-file).
 
@@ -85,9 +85,19 @@ services:
       DEBUG: "true"
 ```
 
+When same variable is declare by multiple sources, precedence applies as:
+
+1. Variables from shell environment
+2. If `--env-file` is not set, variables set by an `.env` file in local working directory (`PWD`)
+3. Variables from file set by `--env-file` or an `.env` file in project directory
+
+You can check variables and values used by Compose to interpolate the compose model by running `docker compose config --environment`.
+
+
+
 #### Additional information 
 
-- If you define an environment variable in your `.env` file, you can reference it directly in your `compose.yml` with the [`environment` attribute](../compose-file/05-services.md#environment). For example, if your `.env` file contains the environment variable `DEBUG=1` and your `compose.yml` file looks like this:
+- If you define a variable in your `.env` file, you can reference it directly in your `compose.yml` with the [`environment` attribute](../compose-file/05-services.md#environment). For example, if your `.env` file contains the environment variable `DEBUG=1` and your `compose.yml` file looks like this:
    ```yaml
     services:
       webapp:
@@ -113,6 +123,7 @@ services:
 > It is not supported by Swarm when running `docker stack deploy`.
 { .important }
 
+
 #### `.env` file syntax
 
 The following syntax rules apply to environment files:
@@ -211,3 +222,33 @@ If an environment variable is not set, Compose substitutes with an empty string.
 > **Note**
 >
 > `postgres:` is not a valid image reference. Docker expects either a reference without a tag, like `postgres` which defaults to the latest image, or with a tag such as `postgres:15`.
+
+
+### local `.env` file _vs_ <project directory> `.env` file
+
+An `.env` file can also be used to declare [pre-defined environment variables](envvars.md) used to control Compose behavior and files to be loaded. When executed without an
+explicit `--env-file` flag, Compose will search for a `.env` file in working directory ([PWD](https://www.gnu.org/software/bash/manual/html_node/Bash-Variables.html#index-PWD)) and load values 
+both for self-configuration and interpolation. If those values define `COMPOSE_FILE` variable which results into project directory being set to another folder, 
+then the latter is also used to load a second `.env` file, which will have lower precedence. 
+
+This mechanism makes it possible to invoke an existing Compose project with a custom set of variables as overrides, without the need to pass environment 
+variables by the command line.
+
+```console
+$ cat .env
+COMPOSE_FILE=../compose.yaml
+POSTGRES_VERSION=9.3
+
+$ cat ../compose.yaml 
+services:
+  db:
+    image: "postgres:${POSTGRES_VERSION}"
+$ cat ../.env
+POSTGRES_VERSION=9.2
+
+$ docker compose config
+services:
+  db:
+    image: "postgres:9.3"
+```
+