@@ -325,16 +325,20 @@ read-write. See examples.

 **--volumes-from**=[]

    Mount volumes from the specified container(s)

-   Will mount volumes from the specified container identified by container-id.

-Once a volume is mounted in a one container it can be shared with other

-containers using the **--volumes-from** option when running those other

-containers. The volumes can be shared even if the original container with the

-mount is not running.

-

-   The container ID may be optionally suffixed with :ro or

-:rw to mount the volumes in read-only or read-write mode, respectively. By

-default, the volumes are mounted in the same mode (read write or read only) as

-the reference container.

+   Mounts already mounted volumes from a source container onto another

+   container. You must supply the source's container-id. To share 

+   a volume, use the **--volumes-from** option when running

+   the target container. You can share volumes even if the source container 

+   is not running.

+

+   By default, Docker mounts the volumes in the same mode (read-write or 

+   read-only) as it is mounted in the source container. Optionally, you 

+   can change this by suffixing the container-id with either the `:ro` or 

+   `:rw ` keyword.

+

+   If the location of the volume from the source container overlaps with

+   data residing on a target container, then the volume hides

+   that data on the target.

 **-w**, **--workdir**=""

    Working directory inside the container

@@ -777,14 +777,28 @@ If you then run `docker stop test`, the container will not exit cleanly - the

     VOLUME ["/data"]

-The `VOLUME` instruction will create a mount point with the specified name

-and mark it as holding externally mounted volumes from native host or other

+The `VOLUME` instruction creates a mount point with the specified name

+and marks it as holding externally mounted volumes from native host or other

 containers. The value can be a JSON array, `VOLUME ["/var/log/"]`, or a plain

 string with multiple arguments, such as `VOLUME /var/log` or `VOLUME /var/log

 /var/db`.  For more information/examples and mounting instructions via the

-Docker client, refer to [*Share Directories via Volumes*](/userguide/dockervolumes/#volume)

+Docker client, refer to 

+[*Share Directories via Volumes*](/userguide/dockervolumes/#volume)

 documentation.

+The `docker run` command initializes the newly created volume with any data 

+that exists at the specified location within the base image. For example, 

+consider the following Dockerfile snippet:

+

+    FROM ubuntu

+    RUN mkdir /myvol

+    RUN echo "hello world" > /myvol/greating

+    VOLUME /myvol

+

+This Dockerfile results in an image that causes `docker run`, to

+create a new mount point at `/myvol` and copy the  `greating` file 

+into the newly created volume.

+

 > **Note**:

 > The list is parsed as a JSON array, which means that

 > you must use double-quotes (") around words not single-quotes (').

@@ -21,19 +21,21 @@ Docker.

 A *data volume* is a specially-designated directory within one or more

 containers that bypasses the [*Union File

-System*](/terms/layer/#union-file-system) to provide several useful features for

-persistent or shared data:

+System*](/terms/layer/#union-file-system). Data volumes provide several 

+useful features for persistent or shared data:

-- Volumes are initialized when a container is created

-- Data volumes can be shared and reused between containers

-- Changes to a data volume are made directly

-- Changes to a data volume will not be included when you update an image

-- Data volumes persist even if the container itself is deleted

+- Volumes are initialized when a container is created. If the container's

+  base image contains data at the specified mount point, that data is 

+  copied into the new volume.

+- Data volumes can be shared and reused among containers.

+- Changes to a data volume are made directly.

+- Changes to a data volume will not be included when you update an image.

+- Data volumes persist even if the container itself is deleted.

 Data volumes are designed to persist data, independent of the container's life 

-cycle. Docker will therefore *never* automatically delete volumes when you remove 

-a container, nor will it "garbage collect" volumes that are no longer referenced 

-by a container.

+cycle. Docker therefore *never* automatically delete volumes when you remove 

+a container, nor will it "garbage collect" volumes that are no longer 

+referenced by a container.

 ### Adding a data volume

@@ -132,6 +134,11 @@ And another:

     $ sudo docker run -d --volumes-from dbdata --name db2 training/postgres

+In this case, if the `postgres` image contained a directory called `/dbdata`

+then mounting the volumes from the `dbdata` container hides the

+`/dbdata` files from the `postgres` image. The result is only the files

+from the `dbdata` container are visible.

+

 You can use multiple `--volumes-from` parameters to bring together multiple data

 volumes from multiple containers.