github.com/vincentwoo/docker@v0.7.3-0.20160116130405-82401a4b13c0/man/docker-cp.1.md (about)

     1  % DOCKER(1) Docker User Manuals
     2  % Docker Community
     3  % JUNE 2014
     4  # NAME
     5  docker-cp - Copy files/folders between a container and the local filesystem.
     6  
     7  # SYNOPSIS
     8  **docker cp**
     9  [**--help**]
    10  CONTAINER:SRC_PATH DEST_PATH|-
    11  
    12  **docker cp**
    13  [**--help**]
    14  SRC_PATH|- CONTAINER:DEST_PATH
    15  
    16  # DESCRIPTION
    17  
    18  The `docker cp` utility copies the contents of `SRC_PATH` to the `DEST_PATH`.
    19  You can copy from the container's file system to the local machine or the
    20  reverse, from the local filesystem to the container. If `-` is specified for
    21  either the `SRC_PATH` or `DEST_PATH`, you can also stream a tar archive from
    22  `STDIN` or to `STDOUT`. The `CONTAINER` can be a running or stopped container.
    23  The `SRC_PATH` or `DEST_PATH` be a file or directory.
    24  
    25  The `docker cp` command assumes container paths are relative to the container's 
    26  `/` (root) directory. This means supplying the initial forward slash is optional; 
    27  The command sees `compassionate_darwin:/tmp/foo/myfile.txt` and
    28  `compassionate_darwin:tmp/foo/myfile.txt` as identical. Local machine paths can
    29  be an absolute or relative value. The command interprets a local machine's
    30  relative paths as relative to the current working directory where `docker cp` is
    31  run.
    32  
    33  The `cp` command behaves like the Unix `cp -a` command in that directories are
    34  copied recursively with permissions preserved if possible. Ownership is set to
    35  the user and primary group at the destination. For example, files copied to a
    36  container are created with `UID:GID` of the root user. Files copied to the local
    37  machine are created with the `UID:GID` of the user which invoked the `docker cp`
    38  command.  If you specify the `-L` option, `docker cp` follows any symbolic link
    39  in the `SRC_PATH`.
    40  
    41  Assuming a path separator of `/`, a first argument of `SRC_PATH` and second
    42  argument of `DEST_PATH`, the behavior is as follows:
    43  
    44  - `SRC_PATH` specifies a file
    45      - `DEST_PATH` does not exist
    46          - the file is saved to a file created at `DEST_PATH`
    47      - `DEST_PATH` does not exist and ends with `/`
    48          - Error condition: the destination directory must exist.
    49      - `DEST_PATH` exists and is a file
    50          - the destination is overwritten with the source file's contents
    51      - `DEST_PATH` exists and is a directory
    52          - the file is copied into this directory using the basename from
    53            `SRC_PATH`
    54  - `SRC_PATH` specifies a directory
    55      - `DEST_PATH` does not exist
    56          - `DEST_PATH` is created as a directory and the *contents* of the source
    57             directory are copied into this directory
    58      - `DEST_PATH` exists and is a file
    59          - Error condition: cannot copy a directory to a file
    60      - `DEST_PATH` exists and is a directory
    61          - `SRC_PATH` does not end with `/.`
    62              - the source directory is copied into this directory
    63          - `SRC_PATH` does end with `/.`
    64              - the *content* of the source directory is copied into this
    65                directory
    66  
    67  The command requires `SRC_PATH` and `DEST_PATH` to exist according to the above
    68  rules. If `SRC_PATH` is local and is a symbolic link, the symbolic link, not
    69  the target, is copied by default. To copy the link target and not the link, 
    70  specify the `-L` option.
    71  
    72  A colon (`:`) is used as a delimiter between `CONTAINER` and its path. You can
    73  also use `:` when specifying paths to a `SRC_PATH` or `DEST_PATH` on a local
    74  machine, for example  `file:name.txt`. If you use a `:` in a local machine path,
    75  you must be explicit with a relative or absolute path, for example:
    76  
    77      `/path/to/file:name.txt` or `./file:name.txt`
    78  
    79  It is not possible to copy certain system files such as resources under
    80  `/proc`, `/sys`, `/dev`, and mounts created by the user in the container.
    81  
    82  Using `-` as the `SRC_PATH` streams the contents of `STDIN` as a tar archive.
    83  The command extracts the content of the tar to the `DEST_PATH` in container's
    84  filesystem. In this case, `DEST_PATH` must specify a directory. Using `-` as
    85  `DEST_PATH` streams the contents of the resource as a tar archive to `STDOUT`.
    86  
    87  # OPTIONS
    88  **-L**, **--follow-link**=*true*|*false*
    89    Follow symbol link in SRC_PATH
    90  
    91  **--help**
    92    Print usage statement
    93  
    94  # EXAMPLES
    95  
    96  Suppose a container has finished producing some output as a file it saves
    97  to somewhere in its filesystem. This could be the output of a build job or
    98  some other computation. You can copy these outputs from the container to a
    99  location on your local host.
   100  
   101  If you want to copy the `/tmp/foo` directory from a container to the
   102  existing `/tmp` directory on your host. If you run `docker cp` in your `~`
   103  (home) directory on the local host:
   104  
   105      $ docker cp compassionate_darwin:tmp/foo /tmp
   106  
   107  Docker creates a `/tmp/foo` directory on your host. Alternatively, you can omit
   108  the leading slash in the command. If you execute this command from your home
   109  directory:
   110  
   111      $ docker cp compassionate_darwin:tmp/foo tmp
   112  
   113  If `~/tmp` does not exist, Docker will create it and copy the contents of
   114  `/tmp/foo` from the container into this new directory. If `~/tmp` already
   115  exists as a directory, then Docker will copy the contents of `/tmp/foo` from
   116  the container into a directory at `~/tmp/foo`.
   117  
   118  When copying a single file to an existing `LOCALPATH`, the `docker cp` command
   119  will either overwrite the contents of `LOCALPATH` if it is a file or place it
   120  into `LOCALPATH` if it is a directory, overwriting an existing file of the same
   121  name if one exists. For example, this command:
   122  
   123      $ docker cp sharp_ptolemy:/tmp/foo/myfile.txt /test
   124  
   125  If `/test` does not exist on the local machine, it will be created as a file
   126  with the contents of `/tmp/foo/myfile.txt` from the container. If `/test`
   127  exists as a file, it will be overwritten. Lastly, if `/test` exists as a
   128  directory, the file will be copied to `/test/myfile.txt`.
   129  
   130  Next, suppose you want to copy a file or folder into a container. For example,
   131  this could be a configuration file or some other input to a long running
   132  computation that you would like to place into a created container before it
   133  starts. This is useful because it does not require the configuration file or
   134  other input to exist in the container image.
   135  
   136  If you have a file, `config.yml`, in the current directory on your local host
   137  and wish to copy it to an existing directory at `/etc/my-app.d` in a container,
   138  this command can be used:
   139  
   140      $ docker cp config.yml myappcontainer:/etc/my-app.d
   141  
   142  If you have several files in a local directory `/config` which you need to copy
   143  to a directory `/etc/my-app.d` in a container:
   144  
   145      $ docker cp /config/. myappcontainer:/etc/my-app.d
   146  
   147  The above command will copy the contents of the local `/config` directory into
   148  the directory `/etc/my-app.d` in the container.
   149  
   150  Finally, if you want to copy a symbolic link into a container, you typically
   151  want to  copy the linked target and not the link itself. To copy the target, use
   152  the `-L` option, for example:
   153  
   154      $ ln -s /tmp/somefile /tmp/somefile.ln
   155      $ docker cp -L /tmp/somefile.ln myappcontainer:/tmp/
   156  
   157  This command copies content of the local `/tmp/somefile` into the file
   158  `/tmp/somefile.ln` in the container. Without `-L` option, the `/tmp/somefile.ln`
   159  preserves its symbolic link but not its content.
   160  
   161  # HISTORY
   162  April 2014, Originally compiled by William Henry (whenry at redhat dot com)
   163  based on docker.com source material and internal work.
   164  June 2014, updated by Sven Dowideit <SvenDowideit@home.org.au>
   165  May 2015, updated by Josh Hawn <josh.hawn@docker.com>