Chapter 57. Incremental Tasks

For a task to process inputs incrementally, that task must contain an incremental task action. This is a task action method that contains a single IncrementalTaskInputs parameter, which indicates to Gradle that the action will process the changed inputs only.

The incremental task action may supply an IncrementalTaskInputs.outOfDate() action for processing any input file that is out-of-date, and a IncrementalTaskInputs.removed() action that executes for any input file that has been removed since the previous execution.

class IncrementalReverseTask extends DefaultTask {
    @InputDirectory
    def File inputDir

    @OutputDirectory
    def File outputDir

    @TaskAction
    void execute(IncrementalTaskInputs inputs) {
        println inputs.incremental ? "CHANGED inputs considered out of date" : "ALL inputs considered out of date"
        inputs.outOfDate({ change ->
            println "out of date: ${change.file.name}"
            def targetFile = project.file("$outputDir/${change.file.name}")
            targetFile.text = change.file.text.reverse()
        } as Action)

        inputs.removed({ change ->
            println "removed: ${change.file.name}"
            def targetFile = project.file("$outputDir/${change.file.name}")
            if (targetFile.exists()) {
                targetFile.delete()
            }
        } as Action)
    }
}

For a simple transformer task like this, the task action simply needs to generate output files for any out-of-date inputs, and delete output files for any removed inputs.

A task may only contain a single incremental task action.

When Gradle has history of a previous task execution, and the only changes to the task execution context since that execution are to input files, then Gradle is able to determine which input files need to be reprocessed by the task. In this case, the IncrementalTaskInputs.outOfDate() action will be executed any input file that was added or modified, and the IncrementalTaskInputs.removed() action will be executed for any removed input file.

However, there are many cases where Gradle is unable to determine which input files need to be reprocessed. Examples include:

In any of these cases, Gradle will consider all of the input files to be outOfDate. The IncrementalTaskInputs.outOfDate() action will be executed for every input file, and the IncrementalTaskInputs.removed() action will not be executed at all.

You can check if Gradle was able to determine the incremental changes to input files with IncrementalTaskInputs.isIncremental().

Given the incremental task implementation above, we can explore the various change scenarios by example. First, consider the an IncrementalReverseTask executed against a set of inputs for the first time. In this case, all inputs will be considered "out of date":

task incrementalReverse(type: IncrementalReverseTask) {
    inputDir = file('inputs')
    outputDir = file("$buildDir/outputs")
}

incrementalTask/
  build.gradle
  inputs/
    1.txt
    2.txt
    3.txt

> gradle -q incrementalReverse
ALL inputs considered out of date
out of date: 1.txt
out of date: 2.txt
out of date: 3.txt

Naturally when the task is executed again with no changes, then task itself is up to date and no files are reported to the task action:

> gradle -q incrementalReverse

When an input file is modified in some way or a new input file is added, then re-executing the task results in those files being reported to IncrementalTaskInputs.outOfDate():

task updatedInputs() << {
    file('inputs/1.txt').text = "Changed content for existing file 1."
    file('inputs/4.txt').text = "Content for new file 4."
}

> gradle -q updatedInputs incrementalReverse
CHANGED inputs considered out of date
out of date: 1.txt
out of date: 4.txt

When an existing input file is removed, then re-executing the task results that file being reported to IncrementalTaskInputs.removed():

task removedInput() << {
    file('inputs/3.txt').delete()
}

> gradle -q removedInput incrementalReverse
CHANGED inputs considered out of date
removed: 3.txt

When an output file is deleted (or modified), then Gradle is unable to determine which input files are out of date. In this case, all input files are reported to the IncrementalTaskInputs.outOfDate() action, and no input files are reported to the IncrementalTaskInputs.removed() action:

task removedOutput() << {
    file("$buildDir/outputs/1.txt").delete()
}

> gradle -q removedOutput incrementalReverse
ALL inputs considered out of date
out of date: 1.txt
out of date: 2.txt
out of date: 3.txt