From 82f5ef2d2562f9e742eb694dc4b0a1f768a4f0de Mon Sep 17 00:00:00 2001 From: Thomas Riccardi Date: Fri, 8 Apr 2016 11:23:48 +0200 Subject: [PATCH] Improve build cache miss doc for `ARG` and `RUN` The documentation already says the cache miss happens only at `ARG` variable usage, not declaration, but there is a very common implicit usage: `RUN`, which this commit documents even more, improving on #21790. Also, use `definition` instead of `declaration`: it's the same thing, and `definition` is already used in this documentation, contrary to `declaration`. Also, distinguish between "instructions" and "variables defined by `ARG` instructions". Signed-off-by: Thomas Riccardi --- docs/reference/builder.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/reference/builder.md b/docs/reference/builder.md index a932276b75..f1838ee0ea 100644 --- a/docs/reference/builder.md +++ b/docs/reference/builder.md @@ -1174,8 +1174,9 @@ To use these, simply pass them on the command line using the `--build-arg `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 first use of the `ARG` variable. The -declaration of the `ARG` variable does not count as a use. +build, then a "cache miss" occurs upon its first usage, not its definition. In +particular, all `RUN` instructions following an `ARG` instruction use the `ARG` +variable implicitly (as an environment variable), thus can cause a cache miss. For example, consider these two Dockerfile: