From cffa6292c2b4301c271ead047bfd75d4f17f4f85 Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Tue, 20 Aug 2024 17:41:00 +0200
Subject: [PATCH 1/2] build: mtime doesn't invalidate cache

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
---
 content/build/cache/invalidation.md | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/content/build/cache/invalidation.md b/content/build/cache/invalidation.md
index a55f5438ec..d799390495 100644
--- a/content/build/cache/invalidation.md
+++ b/content/build/cache/invalidation.md
@@ -21,11 +21,16 @@ The basic rules of build cache invalidation are as follows:
   of the child images is sufficient. However, certain instructions require more
   examination and explanation.
 
-- 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

From e1fe86054d292410b47ab81b37173a3c2e21bb41 Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Tue, 20 Aug 2024 17:54:56 +0200
Subject: [PATCH 2/2] build: rewrite prose about "child images"

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
---
 content/build/cache/invalidation.md | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/content/build/cache/invalidation.md b/content/build/cache/invalidation.md
index d799390495..e4daffc6e0 100644
--- a/content/build/cache/invalidation.md
+++ b/content/build/cache/invalidation.md
@@ -5,21 +5,21 @@ 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, and for `RUN` instructions with bind
   mounts (`RUN --mount=type=bind`), the builder calculates a cache checksum