Gradle Incremental Build: How It Works

Gradle's incremental build is the reason Gradle feels faster than Maven on repeated builds — it treats every task as a pure function and skips re-execution when nothing changed.

How UP-TO-DATE checking works

• Before running any task, Gradle hashes all declared inputs — source files, configuration values, classpath entries — and compares the hash to the stored fingerprint from the last successful execution
• If every input hash matches, the task is marked UP-TO-DATE and skipped entirely — the output from the previous execution is reused
• Content-based, not timestamp-based: touching a file without changing its content does not trigger a rebuild; this distinction matters in CI where every git checkout produces fresh timestamps but identical source files

The build cache — sharing outputs across machines

• When a task runs, Gradle stores its outputs keyed by input hash in the build cache — local by default, shared with a remote cache server optionally
• A developer whose input hash matches a task CI already ran pulls the cached output instead of recompiling — a 30-second compile task takes under 200 milliseconds from cache
• Enable remote cache with buildCache { remote(HttpBuildCache) { url = 'https://your-cache/cache/'; push = System.getenv('CI') != null } } — only CI pushes to the cache; developers only pull

Custom task annotation requirements

• Custom tasks without @Input and @OutputDirectory annotations on their properties re-execute on every build — Gradle cannot determine what changed if inputs and outputs are not declared
• The symptom: a custom task always shows EXECUTED instead of UP-TO-DATE; run with --info to see which input Gradle detected as changed
• Use @InputFiles, @InputDirectory, @OutputFile, @Internal precisely — over-declaring inputs causes false cache misses; under-declaring causes stale output to be used incorrectly