Add some docs about build-arg's impact on the cache

Closes #18017

Signed-off-by: Doug Davis <dug@us.ibm.com>

docs/reference/builder.md

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