Merge pull request moby#9519 from SvenDowideit/1.4-volume-initializat…

…ion-in-docker-create

Talk up the 1.4 change to initialise volumes at  time

docs/sources/reference/commandline/cli.md

@@ -713,13 +713,42 @@ Note that volumes set by `create` may be over-ridden by options set with
 
 Please see the [run command](#run) section for more details.
 
-#### Example
+#### Examples
 
     $ sudo docker create -t -i fedora bash
     6d8af538ec541dd581ebc2a24153a28329acb5268abe5ef868c1f1a261221752
     $ sudo docker start -a -i 6d8af538ec5
     bash-4.2#
 
+As of v1.4.0 container volumes are initialized during the `docker create`
+phase (i.e., `docker run` too). For example, this allows you to `create` the
+`data` volume container, and then use it from another container:
+
+    $ docker create -v /data --name data ubuntu
+    240633dfbb98128fa77473d3d9018f6123b99c454b3251427ae190a7d951ad57
+    $ docker run --rm --volumes-from data ubuntu ls -la /data
+    total 8
+    drwxr-xr-x  2 root root 4096 Dec  5 04:10 .
+    drwxr-xr-x 48 root root 4096 Dec  5 04:11 ..
+
+Similarly, `create` a host directory bind mounted volume container, which
+can then be used from the subsequent container:
+
+    $ docker create -v /home/docker:/docker --name docker ubuntu
+    9aa88c08f319cd1e4515c3c46b0de7cc9aa75e878357b1e96f91e2c773029f03
+    $ docker run --rm --volumes-from docker ubuntu ls -la /docker
+    total 20
+    drwxr-sr-x  5 1000 staff  180 Dec  5 04:00 .
+    drwxr-xr-x 48 root root  4096 Dec  5 04:13 ..
+    -rw-rw-r--  1 1000 staff 3833 Dec  5 04:01 .ash_history
+    -rw-r--r--  1 1000 staff  446 Nov 28 11:51 .ashrc
+    -rw-r--r--  1 1000 staff   25 Dec  5 04:00 .gitconfig
+    drwxr-sr-x  3 1000 staff   60 Dec  1 03:28 .local
+    -rw-r--r--  1 1000 staff  920 Nov 28 11:51 .profile
+    drwx--S---  2 1000 staff  460 Dec  5 00:51 .ssh
+    drwxr-xr-x 32 1000 staff 1140 Dec  5 04:01 docker
+
+
 ## diff
 
 List the changed files and directories in a container᾿s filesystem

docs/sources/userguide/dockervolumes.md

@@ -24,6 +24,7 @@ containers that bypasses the [*Union File
 System*](/terms/layer/#union-file-system) to 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
@@ -32,9 +33,9 @@ persistent or shared data:
 ### Adding a data volume
 
 You can add a data volume to a container using the `-v` flag with the
-`docker run` command. You can use the `-v` multiple times in a single
-`docker run` to mount multiple data volumes. Let's mount a single volume
-now in our web application container.
+`docker create` and `docker run` command. You can use the `-v` multiple times
+to mount multiple data volumes. Let's mount a single volume now in our web
+application container.
 
     $ sudo docker run -d -P --name web -v /webapp training/webapp python app.py
 
@@ -105,8 +106,10 @@ create a named Data Volume Container, and then to mount the data from
 it.
 
 Let's create a new named container with a volume to share.
+While this container doesn't run an application, it reuses the `training/postgres`
+image so that all containers are using layers in common, saveing disk space.
 
-    $ sudo docker run -d -v /dbdata --name dbdata training/postgres echo Data-only container for postgres
+    $ sudo docker create -v /dbdata --name dbdata training/postgres
 
 You can then use the `--volumes-from` flag to mount the `/dbdata` volume in another container.