@@ -562,7 +562,7 @@ ADD has two forms:

 whitespace)

 The `ADD` instruction copies new files, directories or remote file URLs from `<src>`

-and adds them to the filesystem of the container at the path `<dest>`.  

+and adds them to the filesystem of the container at the path `<dest>`.

 Multiple `<src>` resource may be specified but if they are files or

 directories then they must be relative to the source directory that is

@@ -1135,6 +1135,40 @@ corresponding `ARG` instruction in the Dockerfile.

 To use these, simply pass them on the command line using the `--build-arg

 <varname>=<value>` flag.

+### Impact on build caching

+

+`ARG` variables are not persisted into the built image as `ENV` variables are.

+However, `ARG` variables do impact the build cache in similar ways. If a

+Dockerfile defines an `ARG` variable whose value is different from a previous

+build, then a "cache miss" occurs upon its first usage, not its declaration.

+For example, consider this Dockerfile:

+

+```

+1 FROM ubuntu

+2 ARG CONT_IMG_VER

+3 RUN echo $CONT_IMG_VER

+```

+

+If you specify `--build-arg CONT_IMG_VER=<value>` on the command line the

+specification on line 2 does not cause a cache miss; line 3 does cause a cache

+miss. The definition on line 2 has no impact on the resulting image. The `RUN`

+on line 3 executes a command and in doing so defines a set of environment

+variables, including `CONT_IMG_VER`. At that point, the `ARG` variable may

+impact the resulting image, so a cache miss occurs.

+

+Consider another example under the same command line:

+

+```

+1 FROM ubuntu

+2 ARG CONT_IMG_VER

+3 ENV CONT_IMG_VER $CONT_IMG_VER

+4 RUN echo $CONT_IMG_VER

+```

+In this example, the cache miss occurs on line 3. The miss happens because

+the variable's value in the `ENV` references the `ARG` variable and that

+variable is changed through the command line. In this example, the `ENV`

+command causes the image to include the value.

+

 ## ONBUILD

     ONBUILD [INSTRUCTION]