From 1026e719a161c89e466a6d366e3538a55905a860 Mon Sep 17 00:00:00 2001
From: Ulysses Souza <ulyssessouza@gmail.com>
Date: Tue, 19 Jul 2022 17:35:12 +0200
Subject: [PATCH] Add new environment variables precedence matrix

Signed-off-by: Ulysses Souza <ulyssessouza@gmail.com>
---
 _data/toc.yaml                |  8 +++++--
 compose/envvars-precedence.md | 40 +++++++++++++++++++++++++++++++++++
 2 files changed, 46 insertions(+), 2 deletions(-)
 create mode 100644 compose/envvars-precedence.md

diff --git a/_data/toc.yaml b/_data/toc.yaml
index ab70cbcc2bb..7f5da9d2352 100644
--- a/_data/toc.yaml
+++ b/_data/toc.yaml
@@ -1413,8 +1413,12 @@ manuals:
         title: Uninstall Docker Compose
   - path: /compose/gettingstarted/
     title: Getting started
-  - path: /compose/environment-variables/
-    title: Environment variables in Compose
+  - sectiontitle: Environment variables
+    section:
+    - path: /compose/environment-variables/
+      title: Overview
+    - path: /compose/envvars-precedence/
+      title: Environment variables' precedence
   - path: /compose/env-file/
     title: Environment file
   - path: /compose/profiles/
diff --git a/compose/envvars-precedence.md b/compose/envvars-precedence.md
new file mode 100644
index 00000000000..45ba8c6fe94
--- /dev/null
+++ b/compose/envvars-precedence.md
@@ -0,0 +1,40 @@
+---
+title: Environment variables precedence
+description: TODO
+keywords: compose, environment, env file
+---
+
+<style>
+div {
+  color: RoyalBlue; 
+}
+table {
+  font-family: monospace;
+}
+</style>
+
+- Command Line (docker compose run --env <KEY[=VAL]> https://docs.docker.com/engine/reference/commandline/compose_run/#options)
+- Compose File (service::environment section: https://docs.docker.com/compose/compose-file/#environment)
+- Compose File (service::env_file section file: https://docs.docker.com/compose/compose-file/#env_file)
+- Container Image ENV directive (https://docs.docker.com/engine/reference/builder/#env)
+
+When `WHEREAMI` is the variable in case:
+
+| Image (`ENV` directive in Dockerfile) |  OS Environment   | `.env` file on the project root (or overwrite through `docker compose -–env-file <FILE>`) | Compose file (`service::env_file`) |   Compose file (`service::environment`)   | Command line (docker compose run -e <KEY[=VAL]>) |          RESULT          |
+|:-------------------------------------:|:-----------------:|:-----------------------------------------------------------------------------------------:|:----------------------------------:|:-----------------------------------------:|:------------------------------------------------:|:------------------------:|
+|         <div>Dockerfile</div>         |      OS_Env       |                                   WHEREAMI=DotEnv_File                                    |                                    |                                           |                                                  |        Dockerfile        |
+|              Dockerfile               |      OS_Env       |                              WHEREAMI=<div>DotEnv_File</div>                              |                                    |                                           |                     WHEREAMI                     |       DotEnv_File        |
+|              Dockerfile               | <div>OS_Env</div> |                      WHEREAMI=${WHEREAMI:-DotEnv_File_DefaultValue}                       |                                    |                                           |                     WHEREAMI                     |          OS_Env          |
+|         <div>Dockerfile</div>         |      OS_Env       |                      WHEREAMI=${WHEREAMI:-DotEnv_File_DefaultValue}                       |                                    |                                           |                                                  |        Dockerfile        |
+|              Dockerfile               |                   |                 WHEREAMI=${WHEREAMI:-<div>DotEnv_File_DefaultValue</div>}                 |                                    |                                           |                     WHEREAMI                     | DotEnv_File_DefaultValue |
+|              Dockerfile               |      OS_Env       |                      WHEREAMI=${WHEREAMI:-DotEnv_File_DefaultValue}                       |                                    |                                           |         WHEREAMI=<div>Command_Line</div>         |       Command_Line       |
+|              Dockerfile               | <div>OS_Env</div> |                      WHEREAMI=${WHEREAMI:-DotEnv_File_DefaultValue}                       |                                    |                 WHEREAMI                  |                                                  |          OS_Env          |
+|              Dockerfile               |      OS_Env       |                      WHEREAMI=${WHEREAMI:-DotEnv_File_DefaultValue}                       |                                    |  WHEREAMI=<div>Environment_Section</div>  |                                                  |   Environment_Section    |
+|              Dockerfile               |      OS_Env       |                      WHEREAMI=${WHEREAMI:-DotEnv_File_DefaultValue}                       |                                    |       WHEREAMI=Environment_Section        |         WHEREAMI=<div>Command_Line</div>         |       Command_Line       |
+|              Dockerfile               | <div>OS_Env</div> |                      WHEREAMI=${WHEREAMI:-DotEnv_File_DefaultValue}                       |                                    |       WHEREAMI=Environment_Section        |                     WHEREAMI                     |          OS_Env          |
+|              Dockerfile               |      OS_Env       |                      WHEREAMI=${WHEREAMI:-DotEnv_File_DefaultValue}                       |                                    |                 WHEREAMI                  |         WHEREAMI=<div>Command_Line</div>         |       Command_Line       |
+|              Dockerfile               |      OS_Env       |                                                                                           |         WHEREAMI=Env_File          |                                           |         WHEREAMI=<div>Command_Line</div>         |       Command_Line       |
+|              Dockerfile               |      OS_Env       |                                                                                           |         WHEREAMI=Env_File          |  WHEREAMI=<div>Environment_Section</div>  |                                                  |   Environment_Section    |
+|              Dockerfile               |      OS_Env       |                                                                                           |    WHEREAMI=<div>Env_File</div>    |                                           |                                                  |         Env_File         |
+|              Dockerfile               | <div>OS_Env</div> |                                                                                           |                                    | WHEREAMI=${WHEREAMI:-Environment_Section} |                                                  |          OS_Env          |
+|              Dockerfile               | <div>OS_Env</div> |                      WHEREAMI=${WHEREAMI:-DotEnv_File_DefaultValue}                       |                                    | WHEREAMI=${WHEREAMI:-Environment_Section} |                                                  |          OS_Env          |