Merge pull request moby#11305 from moxiegirl/HOSTPATH-text-11144

Clarify behavior of docker cp

api/client/commands.go

@@ -2494,7 +2494,7 @@ func (cli *DockerCli) CmdRun(args ...string) error {
 }
 
 func (cli *DockerCli) CmdCp(args ...string) error {
-	cmd := cli.Subcmd("cp", "CONTAINER:PATH HOSTPATH|-", "Copy files/folders from the PATH to the HOSTPATH. Use '-' to write the data\nas a tar file to STDOUT.", true)
+	cmd := cli.Subcmd("cp", "CONTAINER:PATH HOSTDIR|-", "Copy files/folders from a PATH on the container to a HOSTDIR on the host\nrunning the command. Use '-' to write the data\nas a tar file to STDOUT.", true)
 	cmd.Require(flag.Exact, 2)
 
 	utils.ParseFlags(cmd, args, true)

docs/man/docker-cp.1.md

@@ -2,18 +2,57 @@
 % Docker Community
 % JUNE 2014
 # NAME
-docker-cp - Copy files/folders from the PATH to the HOSTPATH, or STDOUT
+docker-cp - Copy files or folders from a container's PATH to a HOSTDIR
+or to STDOUT.
 
 # SYNOPSIS
 **docker cp**
 [**--help**]
-CONTAINER:PATH HOSTPATH|-
+CONTAINER:PATH HOSTDIR|-
 
 # DESCRIPTION
-Copy files/folders from a container's filesystem to the
-path. Use '-' to write the data as a tar file to STDOUT.
-Paths are relative to the root of the filesystem. Files
-can be copied from a running or stopped container.
+
+Copy files or folders from a `CONTAINER:PATH` to the `HOSTDIR` or to `STDOUT`. 
+The `CONTAINER:PATH` is relative to the root of the container's filesystem. You
+can copy from either a running or stopped container. 
+
+The `PATH` can be a file or directory. The `docker cp` command assumes all
+`PATH` values start at the `/` (root) directory. This means supplying the
+initial forward slash is optional; The command sees
+`compassionate_darwin:/tmp/foo/myfile.txt` and
+`compassionate_darwin:tmp/foo/myfile.txt` as identical.
+
+The `HOSTDIR` refers to a directory on the host. If you do not specify an
+absolute path for your `HOSTDIR` value, Docker creates the directory relative to
+where you run the `docker cp` command. For example, suppose you want to copy the
+`/tmp/foo` directory from a container to the `/tmp` directory on your host. If
+you run `docker cp` in your `~` (home) directory on the host:
+
+		$ docker cp compassionate_darwin:tmp/foo /tmp
+
+Docker creates a `/tmp/foo` directory on your host. Alternatively, you can omit
+the leading slash in the command. If you execute this command from your home directory:
+
+		$ docker cp compassionate_darwin:tmp/foo tmp
+
+Docker creates a `~/tmp/foo` subdirectory.  
+
+When copying files to an existing `HOSTDIR`, the `cp` command adds the new files to
+the directory. For example, this command:
+
+		$ docker cp sharp_ptolemy:/tmp/foo/myfile.txt /tmp
+
+Creates a `/tmp/foo` directory on the host containing the `myfile.txt` file. If
+you repeat the command but change the filename:
+
+		$ docker cp sharp_ptolemy:/tmp/foo/secondfile.txt /tmp
+
+Your host's `/tmp/foo` directory will contain both files:
+
+		$ ls /tmp/foo
+		myfile.txt secondfile.txt
+		
+Finally, use '-' to write the data as a `tar` file to STDOUT.
 
 # OPTIONS
 **--help**

docs/sources/reference/commandline/cli.md

@@ -779,14 +779,13 @@ Supported `Dockerfile` instructions: `ADD`|`CMD`|`ENTRYPOINT`|`ENV`|`EXPOSE`|`FR
 
 ## cp
 
-Copy files/folders from a container's filesystem to the
-path.  Use '-' to write the data as a tar file to STDOUT.
-Paths are relative to the root of the filesystem.
+Copy files or folders from a container's filesystem to the directory on the
+host.  Use '-' to write the data as a tar file to `STDOUT`. `CONTAINER:PATH` is
+relative to the root of the container's filesystem.
 
-    Usage: docker cp CONTAINER:PATH HOSTPATH|-
+    Usage: docker cp CONTAINER:PATH HOSTDIR|-
 
-    Copy files/folders from the PATH to the HOSTPATH. Use '-' to write the data
-	as a tar file to STDOUT.
+    Copy files/folders from the PATH to the HOSTDIR. 
 
 
 ## create