InputChanges - Gradle DSL Version 8.13

# InputChanges

API Documentation: | `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.

### Properties

Property | Description
`incremental` | 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.

### Methods

Method | Description
`getFileChanges(parameter)` | Changes for a parameter.
`getFileChanges(parameter)` | Changes for a parameter.

### Script blocks

No script blocks

### Property details

#### `boolean` `incremental` (read-only)

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`:

- `InputChanges.getFileChanges(org.gradle.api.file.FileCollection)` and `InputChanges.getFileChanges(org.gradle.api.provider.Provider)` report changes to the input files compared to the previous execution.

When `false`:

- Every input file is reported via `InputChanges.getFileChanges(org.gradle.api.file.FileCollection)` and `InputChanges.getFileChanges(org.gradle.api.provider.Provider)` as if it was `ChangeType.ADDED`.

### Method details

#### ``Iterable`<`FileChange`>` `getFileChanges`(`FileCollection` parameter)

Changes for a parameter.

When `InputChanges.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.

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

Changes for a parameter.

When `InputChanges.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.