diff --git a/docs/reference/builder.md b/docs/reference/builder.md index 55c00625..5663e837 100644 --- a/docs/reference/builder.md +++ b/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 `` -and adds them to the filesystem of the container at the path ``. +and adds them to the filesystem of the container at the path ``. Multiple `` 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 =` 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=` 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]