Package org.gradle.work

# Interface InputChanges

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 Details

  - ### 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.

    Note that for inputs with `PathSensitivity.NONE`, instead of a `ChangeType.MODIFIED` event, file modifications can be reported as a pair of an `ChangeType.ADDED` and a `ChangeType.REMOVED` event.

    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.

    Note that for inputs with `PathSensitivity.NONE`, instead of a `ChangeType.MODIFIED` event, file modifications can be reported as a pair of an `ChangeType.ADDED` and a `ChangeType.REMOVED` event.

    Parameters:
      `parameter` - The value of the parameter to query.