Package org.gradle.work

Interface InputChanges

@Incubating
public interface InputChanges

Provides access to any input files that need to be processed by an incremental work action.

An incremental work action is one that accepts a single InputChanges parameter. The work action can then query what changed for an input parameter since the last execution to only process the changes. The following example shows a task which reverses the text in each of its input files. It demonstrates how to use InputChanges to only process the changed files.

 abstract class IncrementalReverseTask extends DefaultTask {
     @Incremental
     @InputDirectory
     abstract DirectoryProperty getInputDir()

     @OutputDirectory
     abstract DirectoryProperty getOutputDir()

     @TaskAction
     void execute(InputChanges inputChanges) {
         inputChanges.getFileChanges(inputDir).each { change ->
             if (change.fileType == FileType.DIRECTORY) return

             def targetFile = outputDir.file(change.normalizedPath).get().asFile
             if (change.changeType == ChangeType.REMOVED) {
                 targetFile.delete()
             } else {
                 targetFile.text = change.file.text.reverse()
             }
         }
     }
 }
 

In the case where Gradle is unable to determine which input files need to be reprocessed, then all of the input files will be reported as ChangeType.ADDED. When such a full rebuild happens, the output files of the work are removed prior to executing the work action. Cases where this occurs include:

• There is no history available from a previous execution.
• A non-file input parameter has changed since the previous execution.
• One or more output files have changed since the previous execution.

Since:

5.4

Method Summary

Modifier and Type	Method	Description
Iterable<FileChange>	getFileChanges(FileCollection parameter)	Changes for a parameter.
Iterable<FileChange>	getFileChanges(Provider<? extends FileSystemLocation> parameter)	Changes for a parameter.
boolean	isIncremental()	Indicates if it was possible for Gradle to determine which input files were out of date compared to a previous execution.

Method Detail

isIncremental

boolean isIncremental()

Indicates if it was possible for Gradle to determine which input files were out of date compared to a previous execution. Incremental inputs are unavailable when history is unavailable (i.e. this piece of work has never been executed before), or if there are changes to non-file input properties, or output files.

When true:

• getFileChanges(FileCollection) and getFileChanges(Provider) report changes to the input files compared to the previous execution.

When false:

• Every input file is reported via getFileChanges(FileCollection) and getFileChanges(Provider) as if it was ChangeType.ADDED.

getFileChanges

Iterable<FileChange> getFileChanges(FileCollection parameter)

Changes for a parameter.

When isIncremental() is false, then all elements of the parameter are returned as ChangeType.ADDED.

Only input file properties annotated with @Incremental or @SkipWhenEmpty can be queried for changes.

Parameters:

parameter - The value of the parameter to query.

getFileChanges

Iterable<FileChange> getFileChanges(Provider<? extends FileSystemLocation> parameter)

Changes for a parameter.

When isIncremental() is false, then all elements of the parameter are returned as ChangeType.ADDED.

This method allows querying properties of type RegularFileProperty and DirectoryProperty for changes. These two types are typically used for @InputFile and @InputDirectory properties.

Only input file properties annotated with @Incremental or @SkipWhenEmpty can be queried for changes.

Parameters:

parameter - The value of the parameter to query.