env file list precedence Compose file (additional clarification) (#3822)

* clarified ordering of env files

* added env_file order of precedence to v1, v2 Compose

Signed-off-by: Victoria Bialas <victoria.bialas@docker.com>

* formatting

Signed-off-by: Victoria Bialas <victoria.bialas@docker.com>

compose/compose-file/compose-file-v1.md

@@ -176,7 +176,8 @@ Add environment variables from a file. Can be a single value or a list.
 If you have specified a Compose file with `docker-compose -f FILE`, paths in
 `env_file` are relative to the directory that file is in.
 
-Environment variables specified in `environment` override these values.
+Environment variables specified in [environment](#environment) _override_
+these values.
 
     env_file: .env
 
@@ -195,9 +196,40 @@ beginning with `#` (i.e. comments) are ignored, as are blank lines.
 > defined in environment files will _not_ be automatically visible during the
 > build.
 
-The value of `VAL` is used as is and not modified at all. For example if the value is
+The value of `VAL` is used as is and not modified at all. For example if the
-surrounded by quotes (as is often the case of shell variables), the quotes will be
+value is surrounded by quotes (as is often the case of shell variables), the
-included in the value passed to Compose.
+quotes will be included in the value passed to Compose.
+
+Keep in mind that _the order of files in the list is significant in determining
+the value assigned to a variable that shows up more than once_. The files in the
+list are processed from the top down. For the same variable specified in file
+`a.env` and assigned a different value in file `b.env`, if `b.env` is
+listed below (after), then the value from `b.env` stands. For example, given the
+following declaration in `docker_compose.yml`:
+
+```yaml
+services:
+  some-service:
+    env_file:
+      - a.env
+      - b.env
+```
+
+And the following files:
+
+```none
+# a.env
+VAR=1
+```
+
+and
+
+```none
+# b.env
+VAR=hello
+```
+
+$VAR will be `hello`.
 
 ### environment
 

compose/compose-file/compose-file-v2.md

@@ -335,7 +335,8 @@ Add environment variables from a file. Can be a single value or a list.
 If you have specified a Compose file with `docker-compose -f FILE`, paths in
 `env_file` are relative to the directory that file is in.
 
-Environment variables specified in `environment` override these values.
+Environment variables specified in [environment](#environment) _override_
+these values.
 
     env_file: .env
 
@@ -355,9 +356,40 @@ beginning with `#` (i.e. comments) are ignored, as are blank lines.
 > build. Use the [args](#args) sub-option of `build` to define build-time
 > environment variables.
 
-The value of `VAL` is used as is and not modified at all. For example if the value is
+The value of `VAL` is used as is and not modified at all. For example if the
-surrounded by quotes (as is often the case of shell variables), the quotes will be
+value is surrounded by quotes (as is often the case of shell variables), the
-included in the value passed to Compose.
+quotes will be included in the value passed to Compose.
+
+Keep in mind that _the order of files in the list is significant in determining
+the value assigned to a variable that shows up more than once_. The files in the
+list are processed from the top down. For the same variable specified in file
+`a.env` and assigned a different value in file `b.env`, if `b.env` is
+listed below (after), then the value from `b.env` stands. For example, given the
+following declaration in `docker_compose.yml`:
+
+```yaml
+services:
+  some-service:
+    env_file:
+      - a.env
+      - b.env
+```
+
+And the following files:
+
+```none
+# a.env
+VAR=1
+```
+
+and
+
+```none
+# b.env
+VAR=hello
+```
+
+$VAR will be `hello`.
 
 ### environment
 

compose/compose-file/index.md

@@ -688,7 +688,8 @@ Add environment variables from a file. Can be a single value or a list.
 If you have specified a Compose file with `docker-compose -f FILE`, paths in
 `env_file` are relative to the directory that file is in.
 
-Environment variables specified in [environment](#environment) override these values.
+Environment variables specified in [environment](#environment) _override_
+these values.
 
     env_file: .env
 
@@ -712,9 +713,12 @@ The value of `VAL` is used as is and not modified at all. For example if the
 value is surrounded by quotes (as is often the case of shell variables), the
 quotes will be included in the value passed to Compose.
 
-Keep in mind that the order of files in the list is significant in determining
+Keep in mind that _the order of files in the list is significant in determining
-the value assigned to a variable that shows up more than once. For example,
+the value assigned to a variable that shows up more than once_. The files in the
-given the following declaration in `docker_compose.yml`:
+list are processed from the top down. For the same variable specified in file
+`a.env` and assigned a different value in file `b.env`, if `b.env` is
+listed below (after), then the value from `b.env` stands. For example, given the
+following declaration in `docker_compose.yml`:
 
 ```yaml
 services: