Merge pull request #20672 from dvdksn/add-copy-cache-mtime

build: mtime doesnt invalidate cache

content/build/cache/invalidation.md

@@ -5,27 +5,32 @@ keywords: build, buildx, buildkit, cache, invalidation, cache miss
 ---
 
 When building an image, Docker steps through the instructions in your
-Dockerfile, executing each in the order specified. For each instruction, Docker
-checks whether it can reuse the instruction from the build cache.
+Dockerfile, executing each in the order specified. For each instruction, the
+[builder](/build/builders/_index.md) checks whether it can reuse the
+instruction from the build cache.
 
 ## General rules
 
 The basic rules of build cache invalidation are as follows:
 
-- Starting with a base image that's already in the cache, the next
-  instruction is compared against all child images derived from that base
-  image to see if one of them was built using the exact same instruction. If
-  not, the cache is invalidated.
+- The builder begins by checking if the base image is already cached. Each
+  subsequent instruction is compared against the cached layers. If no cached
+  layer matches the instruction exactly, the cache is invalidated.
 
-- In most cases, simply comparing the instruction in the Dockerfile with one
-  of the child images is sufficient. However, certain instructions require more
-  examination and explanation.
+- In most cases, comparing the Dockerfile instruction with the corresponding
+  cached layer is sufficient. However, some instructions require additional
+  checks and explanations.
 
-- For the `ADD` and `COPY` instructions, the modification time and size file
-  metadata is used to determine whether cache is valid. During cache lookup,
+- For the `ADD` and `COPY` instructions, and for `RUN` instructions with bind
+  mounts (`RUN --mount=type=bind`), the builder calculates a cache checksum
+  from file metadata to determine whether cache is valid. During cache lookup,
   cache is invalidated if the file metadata has changed for any of the files
   involved.
 
+  The modification time of a file (`mtime`) is not taken into account when
+  calculating the cache checksum. If only the `mtime` of the copied files have
+  changed, the cache is not invalidated.
+
 - Aside from the `ADD` and `COPY` commands, cache checking doesn't look at the
   files in the container to determine a cache match. For example, when processing
   a `RUN apt-get -y update` command the files updated in the container