docs: Updated for docker cp and its API changes

Documented changes to API to enable new `docker cp` behavior.

Added documentation on `docker cp` usage and behavior.

Docker-DCO-1.1-Signed-off-by: Josh Hawn <[email protected]> (github: jlhawn)

Author: Josh Hawn

docs/reference/api/docker_remote_api.md

@@ -68,6 +68,23 @@ Running `docker rmi` emits an **untag** event when removing an image name.  The
 
 ### What's new
 
+`GET /containers/(id)/archive`
+
+**New!**
+Get an archive of filesystem content from a container.
+
+`PUT /containers/(id)/archive`
+
+**New!**
+Upload an archive of content to be extracted to an
+existing directory inside a container's filesystem.
+
+`POST /containers/(id)/copy`
+
+**Deprecated!**
+This copy endpoint has been deprecated in favor of the above `archive` endpoint
+which can be used to download files and directories from a container.
+
 **New!**
 The `hostConfig` option now accepts the field `GroupAdd`, which specifies a list of additional
 groups that the container process will run as.

docs/reference/api/docker_remote_api_v1.20.md

@@ -1039,6 +1039,8 @@ Status Codes:
 
 Copy files or folders of container `id`
 
+**Deprecated** in favor of the `archive` endpoint below.
+
 **Example request**:
 
     POST /containers/4fa6e0f0c678/copy HTTP/1.1
@@ -1061,6 +1063,120 @@ Status Codes:
 -   **404** – no such container
 -   **500** – server error
 
+### Retrieving information about files and folders in a container
+
+`HEAD /containers/(id)/archive`
+
+See the description of the `X-Docker-Container-Path-Stat` header in the
+folowing section.
+
+### Get an archive of a filesystem resource in a container
+
+`GET /containers/(id)/archive`
+
+Get an tar archive of a resource in the filesystem of container `id`.
+
+Query Parameters:
+
+- **path** - resource in the container's filesystem to archive. Required.
+
+    If not an absolute path, it is relative to the container's root directory.
+    The resource specified by **path** must exist. To assert that the resource
+    is expected to be a directory, **path** should end in `/` or  `/.`
+    (assuming a path separator of `/`). If **path** ends in `/.` then this
+    indicates that only the contents of the **path** directory should be
+    copied. A symlink is always resolved to its target.
+
+    **Note**: It is not possible to copy certain system files such as resources
+    under `/proc`, `/sys`, `/dev`, and mounts created by the user in the
+    container.
+
+**Example request**:
+
+        GET /containers/8cce319429b2/archive?path=/root HTTP/1.1
+
+**Example response**:
+
+        HTTP/1.1 200 OK
+        Content-Type: application/x-tar
+        X-Docker-Container-Path-Stat: eyJuYW1lIjoicm9vdCIsInBhdGgiOiIvcm9vdCIsInNpemUiOjQwOTYsIm1vZGUiOjIxNDc0ODQwOTYsIm10aW1lIjoiMjAxNC0wMi0yN1QyMDo1MToyM1oifQ==
+
+        {{ TAR STREAM }}
+
+On success, a response header `X-Docker-Container-Path-Stat` will be set to a
+base64-encoded JSON object containing some filesystem header information about
+the archived resource. The above example value would decode to the following
+JSON object (whitespace added for readability):
+
+        {
+            "name": "root",
+            "path": "/root",
+            "size": 4096,
+            "mode": 2147484096,
+            "mtime": "2014-02-27T20:51:23Z"
+        }
+
+A `HEAD` request can also be made to this endpoint if only this information is
+desired.
+
+Status Codes:
+
+- **200** - success, returns archive of copied resource
+- **400** - client error, bad parameter, details in JSON response body, one of:
+    - must specify path parameter (**path** cannot be empty)
+    - not a directory (**path** was asserted to be a directory but exists as a
+      file)
+- **404** - client error, resource not found, one of:
+    – no such container (container `id` does not exist)
+    - no such file or directory (**path** does not exist)
+- **500** - server error
+
+### Extract an archive of files or folders to a directory in a container
+
+`PUT /containers/(id)/archive`
+
+Upload a tar archive to be extracted to a path in the filesystem of container
+`id`.
+
+Query Parameters:
+
+- **path** - path to a directory in the container
+    to extract the archive's contents into. Required.
+
+    If not an absolute path, it is relative to the container's root directory.
+    The **path** resource must exist.
+- **noOverwriteDirNonDir** - If "1", "true", or "True" then it will be an error
+    if unpacking the given content would cause an existing directory to be
+    replaced with a non-directory and vice versa.
+
+**Example request**:
+
+        PUT /containers/8cce319429b2/archive?path=/vol1 HTTP/1.1
+        Content-Type: application/x-tar
+
+        {{ TAR STREAM }}
+
+**Example response**:
+
+        HTTP/1.1 200 OK
+
+Status Codes:
+
+- **200** – the content was extracted successfully
+- **400** - client error, bad parameter, details in JSON response body, one of:
+    - must specify path parameter (**path** cannot be empty)
+    - not a directory (**path** should be a directory but exists as a file)
+    - unable to overwrite existing directory with non-directory
+      (if **noOverwriteDirNonDir**)
+    - unable to overwrite existing non-directory with directory
+      (if **noOverwriteDirNonDir**)
+- **403** - client error, permission denied, the volume
+    or container rootfs is marked as read-only.
+- **404** - client error, resource not found, one of:
+    – no such container (container `id` does not exist)
+    - no such file or directory (**path** resource does not exist)
+- **500** – server error
+
 ## 2.2 Images
 
 ### List Images

docs/reference/commandline/cp.md

@@ -11,12 +11,81 @@ weight=1
 
 # cp
 
-    Usage: docker cp CONTAINER:PATH HOSTDIR|-
+Copy files/folders between a container and the local filesystem.
 
-    Copy files/folders from the PATH to the HOSTDIR.
+    Usage:  docker cp [options] CONTAINER:PATH LOCALPATH|-
+            docker cp [options] LOCALPATH|- CONTAINER:PATH
 
-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.
+    --help  Print usage statement
 
+In the first synopsis form, the `docker cp` utility copies the contents of
+`PATH` from the filesystem of `CONTAINER` to the `LOCALPATH` (or stream as
+a tar archive to `STDOUT` if `-` is specified).
 
+In the second synopsis form, the contents of `LOCALPATH` (or a tar archive
+streamed from `STDIN` if `-` is specified) are copied from the local machine to
+`PATH` in the filesystem of `CONTAINER`.
+
+You can copy to or from either a running or stopped container. The `PATH` can
+be a file or directory. The `docker cp` command assumes all `CONTAINER:PATH`
+values are relative to the `/` (root) directory of the container. 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. If a `LOCALPATH` value
+is not absolute, is it considered relative to the current working directory.
+
+Behavior is similar to the common Unix utility `cp -a` in that directories are
+copied recursively with permissions preserved if possible. Ownership is set to
+the user and primary group on the receiving end of the transfer. For example,
+files copied to a container will be created with `UID:GID` of the root user.
+Files copied to the local machine will be created with the `UID:GID` of the
+user which invoked the `docker cp` command.
+
+Assuming a path separator of `/`, a first argument of `SRC_PATH` and second
+argument of `DST_PATH`, the behavior is as follows:
+
+- `SRC_PATH` specifies a file
+    - `DST_PATH` does not exist
+        - the file is saved to a file created at `DST_PATH`
+    - `DST_PATH` does not exist and ends with `/`
+        - Error condition: the destination directory must exist.
+    - `DST_PATH` exists and is a file
+        - the destination is overwritten with the contents of the source file
+    - `DST_PATH` exists and is a directory
+        - the file is copied into this directory using the basename from
+          `SRC_PATH`
+- `SRC_PATH` specifies a directory
+    - `DST_PATH` does not exist
+        - `DST_PATH` is created as a directory and the *contents* of the source
+           directory are copied into this directory
+    - `DST_PATH` exists and is a file
+        - Error condition: cannot copy a directory to a file
+    - `DST_PATH` exists and is a directory
+        - `SRC_PATH` does not end with `/.`
+            - the source directory is copied into this directory
+        - `SRC_PAPTH` does end with `/.`
+            - the *content* of the source directory is copied into this
+              directory
+
+The command requires `SRC_PATH` and `DST_PATH` to exist according to the above
+rules. If `SRC_PATH` is local and is a symbolic link, the symbolic link, not
+the target, is copied.
+
+A colon (`:`) is used as a delimiter between `CONTAINER` and `PATH`, but `:`
+could also be in a valid `LOCALPATH`, like `file:name.txt`. This ambiguity is
+resolved by requiring a `LOCALPATH` with a `:` to be made explicit with a
+relative or absolute path, for example:
+
+    `/path/to/file:name.txt` or `./file:name.txt`
+
+It is not possible to copy certain system files such as resources under
+`/proc`, `/sys`, `/dev`, and mounts created by the user in the container.
+
+Using `-` as the first argument in place of a `LOCALPATH` will stream the
+contents of `STDIN` as a tar archive which will be extracted to the `PATH` in
+the filesystem of the destination container. In this case, `PATH` must specify
+a directory.
+
+Using `-` as the second argument in place of a `LOCALPATH` will stream the
+contents of the resource from the source container as a tar archive to
+`STDOUT`.