ENDOCS-2254

content/manuals/compose/how-tos/multiple-compose-files/merge.md

@@ -67,25 +67,167 @@ webapp:
     - "/data"
   environment:
     - DEBUG=1
-    - ANOTHER_VARIABLE=value
 ```
 
-> [!IMPORTANT]
->
-> When you use multiple Compose files, you must make sure all paths in the
-files are relative to the base Compose file (the first Compose file specified
+## Merging rules 
+
+- Paths are evaluated relative to the base file. When you use multiple Compose files, you must make sure all paths in the files are relative to the base Compose file (the first Compose file specified
 with `-f`). This is required because override files need not be valid
 Compose files. Override files can contain small fragments of configuration.
 Tracking which fragment of a service is relative to which path is difficult and
 confusing, so to keep paths easier to understand, all paths must be defined
 relative to the base file.
 
+   >[!TIP]
+   >
+   > You can use `docker compose config` to review your merged configuration and avoid path-related issues.
+
+- Compose copies configurations from the original service over to the local one.
+If a configuration option is defined in both the original service and the local
+service, the local value replaces or extends the original value.
+
+   - For single-value options like `image`, `command` or `mem_limit`, the new value replaces the old value.
+
+      original service:
+
+      ```yaml
+      services:
+        myservice:
+          # ...
+          command: python app.py
+      ```
+
+      local service:
+
+      ```yaml
+      services:
+        myservice:
+          # ...
+          command: python otherapp.py
+      ```
+
+      result:
+
+      ```yaml
+      services:
+        myservice:
+          # ...
+          command: python otherapp.py
+      ```
+
+   - For the multi-value options `ports`, `expose`, `external_links`, `dns`, `dns_search`, and `tmpfs`, Compose concatenates both sets of values:
+
+      original service:
+
+      ```yaml
+      services:
+        myservice:
+          # ...
+          expose:
+            - "3000"
+      ```
+
+      local service:
+
+      ```yaml
+      services:
+        myservice:
+          # ...
+          expose:
+            - "4000"
+            - "5000"
+      ```
+
+      result:
+
+      ```yaml
+      services:
+        myservice:
+          # ...
+          expose:
+            - "3000"
+            - "4000"
+            - "5000"
+      ```
+
+   - In the case of `environment`, `labels`, `volumes`, and `devices`, Compose "merges" entries together with locally defined values taking precedence. For `environment` and `labels`, the environment variable or label name determines which value is used:
+
+      original service:
+
+      ```yaml
+      services:
+        myservice:
+          # ...
+          environment:
+            - FOO=original
+            - BAR=original
+      ```
+
+      local service:
+
+      ```yaml
+      services:
+        myservice:
+          # ...
+          environment:
+            - BAR=local
+            - BAZ=local
+      ```
+
+     result:
+
+      ```yaml
+      services:
+        myservice:
+          # ...
+          environment:
+            - FOO=original
+            - BAR=local
+            - BAZ=local
+      ```
+
+   - Entries for `volumes` and `devices` are merged using the mount path in the container:
+
+      original service:
+
+      ```yaml
+      services:
+        myservice:
+          # ...
+          volumes:
+            - ./original:/foo
+            - ./original:/bar
+      ```
+
+      local service:
+
+      ```yaml
+      services:
+        myservice:
+          # ...
+          volumes:
+            - ./local:/bar
+            - ./local:/baz
+      ```
+
+      result:
+
+      ```yaml
+      services:
+        myservice:
+          # ...
+          volumes:
+            - ./original:/foo
+            - ./local:/bar
+            - ./local:/baz
+      ```
+
+For more merging rules, see [Merge and override](/reference/compose-file/merge.md) in the Compose Specification. 
+
 ### Additional information
 
 - Using `-f` is optional. If not provided, Compose searches the working directory and its parent directories for a `compose.yml` and a `compose.override.yml` file. You must supply at least the `compose.yml` file. If both files exist on the same directory level, Compose combines them into a single configuration.
 
-- When you use multiple Compose files, all paths in the files are relative to the first configuration file specified with `-f`. You can  use the `--project-directory` option to override this base path.
-
 - You can use a `-f` with `-` (dash) as the filename to read the configuration from `stdin`. For example: 
    ```console
    $ docker compose -f - <<EOF
@@ -129,156 +271,6 @@ relative to the base file.
    Status: Downloaded newer image for postgres:latest
    ```
 
-## Merging rules
-
-Compose copies configurations from the original service over to the local one.
-If a configuration option is defined in both the original service and the local
-service, the local value replaces or extends the original value.
-
-For single-value options like `image`, `command` or `mem_limit`, the new value
-replaces the old value.
-
-original service:
-
-```yaml
-services:
-  myservice:
-    # ...
-    command: python app.py
-```
-
-local service:
-
-```yaml
-services:
-  myservice:
-    # ...
-    command: python otherapp.py
-```
-
-result:
-
-```yaml
-services:
-  myservice:
-    # ...
-    command: python otherapp.py
-```
-
-For the multi-value options `ports`, `expose`, `external_links`, `dns`,
-`dns_search`, and `tmpfs`, Compose concatenates both sets of values:
-
-original service:
-
-```yaml
-services:
-  myservice:
-    # ...
-    expose:
-      - "3000"
-```
-
-local service:
-
-```yaml
-services:
-  myservice:
-    # ...
-    expose:
-      - "4000"
-      - "5000"
-```
-
-result:
-
-```yaml
-services:
-  myservice:
-    # ...
-    expose:
-      - "3000"
-      - "4000"
-      - "5000"
-```
-
-In the case of `environment`, `labels`, `volumes`, and `devices`, Compose
-"merges" entries together with locally defined values taking precedence. For
-`environment` and `labels`, the environment variable or label name determines
-which value is used:
-
-original service:
-
-```yaml
-services:
-  myservice:
-    # ...
-    environment:
-      - FOO=original
-      - BAR=original
-```
-
-local service:
-
-```yaml
-services:
-  myservice:
-    # ...
-    environment:
-      - BAR=local
-      - BAZ=local
-```
-
-result:
-
-```yaml
-services:
-  myservice:
-    # ...
-    environment:
-      - FOO=original
-      - BAR=local
-      - BAZ=local
-```
-
-Entries for `volumes` and `devices` are merged using the mount path in the
-container:
-
-original service:
-
-```yaml
-services:
-  myservice:
-    # ...
-    volumes:
-      - ./original:/foo
-      - ./original:/bar
-```
-
-local service:
-
-```yaml
-services:
-  myservice:
-    # ...
-    volumes:
-      - ./local:/bar
-      - ./local:/baz
-```
-
-result:
-
-```yaml
-services:
-  myservice:
-    # ...
-    volumes:
-      - ./original:/foo
-      - ./local:/bar
-      - ./local:/baz
-```
-
-For more merging rules, see [Merge and override](/reference/compose-file/merge.md) in the Compose Specification. 
-
 ## Example
 
 A common use case for multiple files is changing a development Compose app
@@ -335,7 +327,7 @@ services:
 When you run `docker compose up` it reads the overrides automatically.
 
 To use this Compose app in a production environment, another override file is created, which might be stored in a different git
-repo or managed by a different team.
+repository or managed by a different team.
 
 `compose.prod.yml`