The Build Cache

In one sentence: The builder can skip an instruction and reuse its old layer if — and only if — the parent layer and the instruction (including the checksums of any files it copies) are both unchanged; one miss invalidates everything after it.

The cache key

A cached layer is reusable when the world that produced it is provably identical. The builder's cache key is: parent layer ID + instruction text, and for COPY/ADD also the checksums of the copied files (the text COPY src/ /app doesn't change when your source does — the content check catches that). Because each key includes the parent, a single miss changes every descendant's parent, so everything after the first miss rebuilds. This cascade is why instruction order is a real design skill: stable things first, volatile things last.

flowchart TB
  I["next instruction"] --> Q1{"parent layer
cache hit so far?"}
  Q1 -- no --> MISS["rebuild this layer
(and all after it)"]
  Q1 -- yes --> Q2{"instruction text
unchanged?"}
  Q2 -- no --> MISS
  Q2 -- yes --> Q3{"COPY/ADD file
checksums unchanged?"}
  Q3 -- no --> MISS
  Q3 -- "yes / not a COPY" --> HIT["reuse cached layer
(skip execution)"]
  style HIT fill:#f0faf2,stroke:#1f7a34
  style MISS fill:#fff8ec,stroke:#f2ddb0
    

The cascade in action

A build file ordered COPY deps-list → RUN install → COPY src/ → RUN compile touches only source code between builds. The expensive dependency install stays cached; only the last two steps rerun:

sequenceDiagram
  participant B as Builder
  participant C as Cache
  B->>C: COPY deps-list — key: parent+text+checksum
  C-->>B: HIT — reuse layer 1
  B->>C: RUN install — parent cached, text same
  C-->>B: HIT — reuse layer 2 (the slow one, skipped!)
  B->>C: COPY src/ — checksum differs
  C-->>B: MISS — rebuild layer 3
  B->>C: RUN compile — parent changed
  C-->>B: MISS by cascade — rebuild layer 4