Merge pull request moby#4800 from dvdksn/dockerfile-reference-copy-fi…

…xups

docs: dockerfile copy fixups

frontend/dockerfile/docs/reference.md

@@ -453,7 +453,7 @@ The exec form is parsed as a JSON array, which means that
 you must use double-quotes (") around words, not single-quotes (').
 
 ```dockerfile
-ENTRYPOINT ["/bin/bash", "-c", "echo", "hello"]
+ENTRYPOINT ["/bin/bash", "-c", "echo hello"]
 ```
 
 The exec form is best used to specify an `ENTRYPOINT` instruction, combined
@@ -564,8 +564,10 @@ The image can be any valid image.
   `FROM` instruction. Each `FROM` instruction clears any state created by previous
   instructions.
 - Optionally a name can be given to a new build stage by adding `AS name` to the
-  `FROM` instruction. The name can be used in subsequent `FROM` and
-  `COPY --from=<name>` instructions to refer to the image built in this stage.
+  `FROM` instruction. The name can be used in subsequent `FROM <name>`,
+  [`COPY --from=<name>`](#copy---from),
+  and [`RUN --mount=type=bind,from=<name>`](#run---mounttypebind) instructions
+  to refer to the image built in this stage.
 - The `tag` or `digest` values are optional. If you omit either of them, the
   builder assumes a `latest` tag by default. The builder returns an error if it
   can't find the `tag` value.
@@ -786,7 +788,7 @@ with support for passphrases.
 | `uid`      | User ID for socket. Default `0`.                                                               |
 | `gid`      | Group ID for socket. Default `0`.                                                              |
 
-#### Example: access to Gitlab
+#### Example: access to GitLab
 
 ```dockerfile
 # syntax=docker/dockerfile:1
@@ -1361,6 +1363,7 @@ COPY [OPTIONS] ["<src>", ... "<dest>"]
 
 The available `[OPTIONS]` are:
 
+- [`--from`](#copy---from)
 - [`--chown`](#copy---chown---chmod)
 - [`--chmod`](#copy---chown---chmod)
 - [`--link`](#copy---link)
@@ -1426,10 +1429,10 @@ attempted to be used instead.
 
 `COPY` obeys the following rules:
 
-- The `<src>` path must be inside the build context;
-  you can't use `COPY ../something /something`, because the builder can only
-  access files from the context, and `../something` specifies a parent file or
-  directory of the build context root.
+- The `<src>` path is resolved relative to the build context.
+  If you specify a relative path leading outside of the build context, such as
+  `COPY ../something /something`, parent directory paths are stripped out automatically.
+  The effective source path in this example becomes `COPY something /something`
 
 - If `<src>` is a directory, the entire contents of the directory are copied,
   including filesystem metadata.
@@ -1462,6 +1465,42 @@ attempted to be used instead.
 > guide – Leverage build cache](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/#leverage-build-cache)
 > for more information.
 
+### COPY --from
+
+By default, the `COPY` instruction copies files from the build context. The
+`COPY --from` flag lets you copy files from an image, a build stage,
+or a named context instead.
+
+```dockerfile
+COPY [--from=<image|stage|context>] <src> ... <dest>
+```
+
+To copy from a build stage in a
+[multi-stage build](https://docs.docker.com/build/building/multi-stage/),
+specify the name of the stage you want to copy from. You specify stage names
+using the `AS` keyword with the `FROM` instruction.
+
+```dockerfile
+# syntax=docker/dockerfile:1
+FROM alpine AS build
+COPY . .
+RUN apk add clang
+RUN clang -o /hello hello.c
+
+FROM scratch
+COPY --from=build /hello /
+```
+
+You can also copy files directly from other images. The following example
+copies an `nginx.conf` file from the official Nginx image.
+
+```dockerfile
+COPY --from=nginx:latest /etc/nginx/nginx.conf /nginx.conf
+```
+
+The source path of `COPY --from` is always resolved from filesystem root of the
+image or stage that you specify.
+
 ### COPY --chown --chmod
 
 > **Note**
@@ -2441,15 +2480,11 @@ ONBUILD ADD . /app/src
 ONBUILD RUN /usr/local/bin/python-build --dir /app/src
 ```
 
-> **Warning**
->
-> Chaining `ONBUILD` instructions using `ONBUILD ONBUILD` isn't allowed.
-{ .warning }
+### ONBUILD limitations
 
-> **Warning**
->
-> The `ONBUILD` instruction may not trigger `FROM` or `MAINTAINER` instructions.
-{ .warning }
+- Chaining `ONBUILD` instructions using `ONBUILD ONBUILD` isn't allowed.
+- The `ONBUILD` instruction may not trigger `FROM` or `MAINTAINER` instructions.
+- `ONBUILD COPY --from` is [not supported](https://github.com/moby/buildkit/issues/816).
 
 ## STOPSIGNAL