Clarify behavior of docker cp

The STDOUT behavior of cp is not yet released in 1.50 so removed.
Also, tested against 1.5 all other behaviors and extended documentation to match.
Renamed HOSTPATH to HOSTDIR to give a self documenting name.

Adding back in the references to STDOUT
fix the command string
Entering Doug's comment re append and ~/tmp/foo in the glass
Adding in Doug's comments regarding PATHs and missing |-
Updating with James comments

Signed-off-by: Mary Anthony <mary@docker.com>

api/client/commands.go

@@ -2458,7 +2458,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

@@ -756,14 +756,13 @@ Supported `Dockerfile` instructions: `CMD`, `ENTRYPOINT`, `ENV`, `EXPOSE`,
 
 ## 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