@@ -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.

@@ -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

@@ -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`.

@@ -2,69 +2,150 @@

 % Docker Community

 % JUNE 2014

 # NAME

-docker-cp - Copy files or folders from a container's PATH to a HOSTDIR

-or to STDOUT.

+docker-cp - Copy files/folders between a container and the local filesystem.

 # SYNOPSIS

 **docker cp**

 [**--help**]

-CONTAINER:PATH HOSTDIR|-

+CONTAINER:PATH LOCALPATH|-

+LOCALPATH|- CONTAINER:PATH

 # DESCRIPTION

-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. 

+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).

-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

+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.

+`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`.

+

+# OPTIONS

+**--help**

+  Print usage statement

+

+# EXAMPLES

+

+Suppose a container has finished producing some output as a file it saves

+to somewhere in its filesystem. This could be the output of a build job or

+some other computation. You can copy these outputs from the container to a

+location on your local host.

-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:

+If you want to copy the `/tmp/foo` directory from a container to the

+existing `/tmp` directory on your host. If you run `docker cp` in your `~`

+(home) directory on the local 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:

+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.  

+If `~/tmp` does not exist, Docker will create it and copy the contents of

+`/tmp/foo` from the container into this new directory. If `~/tmp` already

+exists as a directory, then Docker will copy the contents of `/tmp/foo` from

+the container into a directory at `~/tmp/foo`.

-When copying files to an existing `HOSTDIR`, the `cp` command adds the new files to

-the directory. For example, this command:

+When copying a single file to an existing `LOCALPATH`, the `docker cp` command

+will either overwrite the contents of `LOCALPATH` if it is a file or place it

+into `LOCALPATH` if it is a directory, overwriting an existing file of the same

+name if one exists. For example, this command:

-		$ docker cp sharp_ptolemy:/tmp/foo/myfile.txt /tmp

+		$ docker cp sharp_ptolemy:/tmp/foo/myfile.txt /test

-Creates a `/tmp/foo` directory on the host containing the `myfile.txt` file. If

-you repeat the command but change the filename:

+If `/test` does not exist on the local machine, it will be created as a file

+with the contents of `/tmp/foo/myfile.txt` from the container. If `/test`

+exists as a file, it will be overwritten. Lastly, if `/tmp` exists as a

+directory, the file will be copied to `/test/myfile.txt`.

-		$ docker cp sharp_ptolemy:/tmp/foo/secondfile.txt /tmp

+Next, suppose you want to copy a file or folder into a container. For example,

+this could be a configuration file or some other input to a long running

+computation that you would like to place into a created container before it

+starts. This is useful because it does not require the configuration file or

+other input to exist in the container image.

-Your host's `/tmp/foo` directory will contain both files:

+If you have a file, `config.yml`, in the current directory on your local host

+and wish to copy it to an existing directory at `/etc/my-app.d` in a container,

+this command can be used:

-		$ ls /tmp/foo

-		myfile.txt secondfile.txt

-		

-Finally, use '-' to write the data as a `tar` file to STDOUT.

+		$ docker cp config.yml myappcontainer:/etc/my-app.d

-# OPTIONS

-**--help**

-  Print usage statement

+If you have several files in a local directory `/config` which you need to copy

+to a directory `/etc/my-app.d` in a container:

-# EXAMPLES

-An important shell script file, created in a bash shell, is copied from

-the exited container to the current dir on the host:

+		$ docker cp /config/. myappcontainer:/etc/my-app.d

-    # docker cp c071f3c3ee81:setup.sh .

+The above command will copy the contents of the local `/config` directory into

+the directory `/etc/my-app.d` in the container.

 # HISTORY

 April 2014, Originally compiled by William Henry (whenry at redhat dot com)

 based on docker.com source material and internal work.

 June 2014, updated by Sven Dowideit <SvenDowideit@home.org.au>

+May 2015, updated by Josh Hawn <josh.hawn@docker.com>