From f769463646dee71857a1dc312ee2667599e34c5b Mon Sep 17 00:00:00 2001
From: Christian Klaussner <christian@klaussner.me>
Date: Tue, 30 Jan 2018 00:45:25 +0100
Subject: [PATCH] Explain how `volumes` and `devices` are merged (#5852)

---
 compose/extends.md | 24 ++++++++++++++++++++++--
 1 file changed, 22 insertions(+), 2 deletions(-)

diff --git a/compose/extends.md b/compose/extends.md
index e299ac8ab2..83a6841c8b 100644
--- a/compose/extends.md
+++ b/compose/extends.md
@@ -326,8 +326,10 @@ For the **multi-value options** `ports`, `expose`, `external_links`, `dns`,
       - "4000"
       - "5000"
 
-In the case of `environment`, `labels`, `volumes` and `devices`, Compose
-"merges" entries together with locally-defined values taking precedence:
+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
     environment:
@@ -345,6 +347,24 @@ In the case of `environment`, `labels`, `volumes` and `devices`, Compose
       - BAR=local
       - BAZ=local
 
+Entries for `volumes` and `devices` are merged using the mount path in the
+container:
+
+    # original service
+    volumes:
+      - ./original:/foo
+      - ./original:/bar
+
+    # local service
+    volumes:
+      - ./local:/bar
+      - ./local:/baz
+
+    # result
+    volumes:
+      - ./original:/foo
+      - ./local:/bar
+      - ./local:/baz