Update docs about using multiple -f arguments

Signed-off-by: Daniel Nephin <[email protected]>

docs/reference/docker-compose.md

@@ -14,7 +14,7 @@ weight=-2
 
 ```
 Usage:
-  docker-compose [options] [COMMAND] [ARGS...]
+  docker-compose [-f=<arg>...] [options] [COMMAND] [ARGS...]
   docker-compose -h|--help
 
 Options:
@@ -41,20 +41,62 @@ Commands:
   unpause            Unpause services
   up                 Create and start containers
   migrate-to-labels  Recreate containers to add labels
+  version            Show the Docker-Compose version information
 ```
 
-The Docker Compose binary. You use this command to build and manage multiple services in Docker containers.
+The Docker Compose binary. You use this command to build and manage multiple
+services in Docker containers.
 
-Use the `-f` flag to specify the location of a Compose configuration file. This
-flag is optional. If you don't provide this flag. Compose looks for a file named
-`docker-compose.yml` in the  working directory. If the file is not found,
-Compose looks in each parent directory successively, until it finds the file.
+Use the `-f` flag to specify the location of a Compose configuration file. You
+can supply multiple `-f` configuration files. When you supply multiple files,
+Compose combines them into a single configuration. Compose builds the
+configuration in the order you supply the files. Subsequent files override and
+add to their successors.
 
-Use a `-` as the filename to read configuration file from stdin. When stdin is
-used all paths in the configuration are relative to the current working
-directory.
+For example, consider this command line:
+
+```
+$ docker-compose -f docker-compose.yml -f docker-compose.admin.yml run backup_db`
+```
+
+The `docker-compose.yml` file might specify a `webapp` service.
+
+```
+webapp:
+  image: examples/web
+  ports:
+    - "8000:8000"
+  volumes:
+    - "/data"
+```
+
+If the `docker-compose.admin.yml` also specifies this same service, any matching
+fields will override the previous file. New values, add to the `webapp` service
+configuration.
+
+```
+webapp:
+  build: .
+  environment:
+    - DEBUG=1
+```
+
+Use a `-f` with `-` (dash) as the filename to read the configuration from
+stdin. When stdin is used all paths in the configuration are
+relative to the current working directory.
+
+The `-f` flag is optional. If you don't provide this flag on the command line,
+Compose traverses the working directory and its subdirectories looking for a
+`docker-compose.yml` and a `docker-compose.override.yml` file. You must supply
+at least the `docker-compose.yml` file. If both files are present, Compose
+combines the two files into a single configuration. The configuration in the
+`docker-compose.override.yml` file is applied over and in addition to the values
+in the `docker-compose.yml` file.
+
+Each configuration has a project name. If you supply a `-p` flag, you can
+specify a project name. If you don't specify the flag, Compose uses the current
+directory name.
 
-Each configuration can has a project name. If you supply a `-p` flag, you can specify a project name. If you don't specify the flag, Compose uses the current directory name.
 
 ## Where to go next