Incremental Build

An incremental build is a build that reuses the outputs of the previous build and recompiles only the units whose inputs changed. It works by keeping a record of what produced each output, then comparing that record against the current sources so every unchanged unit can be skipped.

The record is the whole mechanism. On a developer machine it survives because the build directory stays on disk between builds. In GitHub Actions the job starts on a machine that is provisioned for that job and deleted when the job ends (GitHub-hosted runners reference, checked on 2026-08-13), so the next run has nothing to compare against and compiles the whole tree.

Definition

An incremental build has three parts, and losing any one of them turns the next build into a full build.

1. Outputs from an earlier build, still on disk: object files, generated headers, compiled classes, linked binaries.
2. A record of the inputs that produced each output. Depending on the tool this is the modification time of the output file itself, a separate fingerprint file written alongside it, or a hash stored in a cache directory.
3. A staleness rule that reads the record and decides, per unit, whether to reuse the output or rebuild it.

Deleting the outputs forces a full compile. Deleting the record forces a full compile even when the outputs are all present, because the build system has no way to prove they are current and treats an unprovable output as stale.

The two staleness rules

Build systems answer the staleness question in one of two ways, and the difference decides how a build behaves after a fresh checkout.

Timestamp rules compare modification times. An output is current when every input that feeds it has a modification time older than the output. The comparison is cheap because the filesystem already stores the numbers, and it is exact only while the timestamps mean what the tool assumes they mean.

Content rules compare hashes. The tool hashes the source text, the compiler identity, and the flag set, then looks for an output stored under that hash. Modification times are irrelevant, so a file whose timestamp moved but whose bytes did not still resolves to the same entry.

The table below shows where each build system keeps its record and which rule it applies. Documentation links are the upstream project references, checked on 2026-08-13.

Why a fresh workspace breaks the timestamp rule

A checkout writes every file it creates with the current time, because the commit does not carry modification times and the tool has nothing else to write. A restored archive behaves the opposite way: tar sets each extracted file back to the modification time it had when the archive was written.

Put those two together in one job and the ordering inverts. Every source file is stamped with the moment the job started, while every restored object file carries a stamp from an earlier day. A timestamp rule reads that and marks the entire tree out of date, which is the correct answer to the question it was asked. Content rules are unaffected, which is why a Go build or a ccache-backed C build recovers from a restore while a make or Cargo build does not.

Example

This workflow builds a Rust crate on a clean job. Cargo writes its outputs and its fingerprint database into target/, and both live only as long as the machine does.

name: build
on: push

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: cargo build --release

Every push runs the same three operations: a fresh machine, a fresh clone, an empty target/. Cargo finds no fingerprint files, so it compiles every crate in the dependency graph and the workspace itself, then the machine is deleted along with everything it produced.

Now add a cache step so target/ survives, and trace what changes.

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/cache@v4
        with:
          path: target
          key: ${{ runner.os }}-cargo-target-${{ hashFiles('Cargo.lock') }}
          restore-keys: ${{ runner.os }}-cargo-target-
      - run: cargo build --release

The three runs below start from an empty store and change one source file between run 2 and run 3.

Run 2 is the shape that surprises people. The outputs are on disk, the fingerprints are on disk, and the build still compiles everything, because the checkout moved the source timestamps forward past the record. A build directory that persists on the machine between runs avoids the inversion entirely: the sources keep the timestamps they had when they were last written, the outputs keep theirs, and the ordering the build system depends on holds.

Related Terms

• Making incremental builds work on GitHub Actions: the workspace shapes that keep a build directory and its timestamps intact across runs, and which build systems recover from a plain cache restore.
• Compiler cache and how it differs from an incremental build: the content-keyed store of compiled objects that survives a timestamp reset, and where the two mechanisms overlap.
• Snapshot runner labels and what the saved image keeps: the label suffixes that boot a job from a saved machine image instead of a base image.
• WarpBuild snapshot runner documentation: the snapshot.enabled and snapshot.key label options, the save action inputs, and the documented limitations.
• GitHub-hosted runners reference: how a hosted runner is provisioned for one job and deleted afterwards.
• WarpBuild pricing: per minute rates by runner type.