anchor.diff:  > gradle -q incrementalReverse
   include::{samplesPath}/userguide/tasks/incrementalTask/incrementalTaskFirstRun.out[]
   ----
  -
  -Naturally when the task is executed again with no changes, then the entire task is up to date and no files are reported to the task action:
  -
  -=== Example: Running the incremental task with unchanged inputs
  -
  -.Output of **`gradle -q incrementalReverse`**
  +====
  +
  +Naturally when the task is executed again with no changes, then the entire task is up to date and no files are reported to the task action (which is why there is no output):
  +
  +.Running the incremental task with unchanged inputs
  +====
  +.Output of `gradle -q incrementalReverse`
   ----
   > gradle -q incrementalReverse
   include::{samplesPath}/userguide/tasks/incrementalTask/incrementalTaskNoChange.out[]
   ----
  -
  -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 returned by link:{groovyDslPath}/org.gradle.work.InputChanges.html#org.gradle.work.InputChanges:getFileChanges(org.gradle.api.file.FileCollection)[InputChanges.getFileChanges]:
  +====
  +
  +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 returned by link:{groovyDslPath}/org.gradle.work.InputChanges.html#org.gradle.work.InputChanges:getFileChanges(org.gradle.api.file.FileCollection)[InputChanges.getFileChanges()].
  +The following example modifies the content of one file and adds another before running the incremental task:
   
   .Running the incremental task with updated input files
   ====
   include::sample[dir="userguide/tasks/incrementalTask/groovy",files="build.gradle[tags=updated-inputs]"]
   include::sample[dir="userguide/tasks/incrementalTask/kotlin",files="build.gradle.kts[tags=updated-inputs]"]
  -====
  -
  -.Output of **`gradle -q updateInputs incrementalReverse`**
  +
  +.Output of `gradle -q updateInputs incrementalReverse`
   ----
   > gradle -q updateInputs incrementalReverse
   include::{samplesPath}/userguide/tasks/incrementalTask/incrementalTaskUpdatedInputs.out[]
   ----
  -
  -When an existing input file is removed, then re-executing the task results in that file being returned by link:{groovyDslPath}/org.gradle.work.InputChanges.html#org.gradle.work.InputChanges:getFileChanges(org.gradle.api.file.FileCollection)[InputChanges.getFileChanges] as `REMOVED`:
  +====
  +
  +NOTE: The various mutation tasks (`updateInputs`, `removeInput`, etc) are only present to demonstrate the behavior of incremental tasks.
  +They should not be viewed as the kinds of tasks or task implementations you should have in your own build scripts.
  +
  +When an existing input file is removed, then re-executing the task results in that file being returned by link:{groovyDslPath}/org.gradle.work.InputChanges.html#org.gradle.work.InputChanges:getFileChanges(org.gradle.api.file.FileCollection)[InputChanges.getFileChanges()] as `REMOVED`.
  +The following example removes one of the existing files before executing the incremental task:
   
   .Running the incremental task with an input file removed
   ====
   include::sample[dir="userguide/tasks/incrementalTask/groovy",files="build.gradle[tags=removed-input]"]
   include::sample[dir="userguide/tasks/incrementalTask/kotlin",files="build.gradle.kts[tags=removed-input]"]
  -====
  -
  -.Output of **`gradle -q removeInput incrementalReverse`**
  +
  +.Output of `gradle -q removeInput incrementalReverse`
   ----
   > gradle -q removeInput incrementalReverse
   include::{samplesPath}/userguide/tasks/incrementalTask/incrementalTaskRemovedInput.out[]
   ----
  -
  -When an output file is deleted (or modified), then Gradle is unable to determine which input files are out of date.
  -In this case, details for _all_ input files for the given property are returned by link:{groovyDslPath}/org.gradle.work.InputChanges.html#org.gradle.work.InputChanges:getFileChanges(org.gradle.api.file.FileCollection)[InputChanges.getFileChanges]:
  +====
  +
  +When an _output_ file is deleted (or modified), then Gradle is unable to determine which input files are out of date.
  +In this case, details for _all_ the input files for the given property are returned by link:{groovyDslPath}/org.gradle.work.InputChanges.html#org.gradle.work.InputChanges:getFileChanges(org.gradle.api.file.FileCollection)[InputChanges.getFileChanges()].
  +The following example removes just one of the output files from the build directory, but notice how all the input files are considered to be `ADDED`:
   
   .Running the incremental task with an output file removed
   ====
   include::sample[dir="userguide/tasks/incrementalTask/groovy",files="build.gradle[tags=removed-output]"]
   include::sample[dir="userguide/tasks/incrementalTask/kotlin",files="build.gradle.kts[tags=removed-output]"]
  -====
  -
  -.Output of **`gradle -q removeOutput incrementalReverse`**
  +
  +.Output of `gradle -q removeOutput incrementalReverse`
   ----
   > gradle -q removeOutput incrementalReverse
   include::{samplesPath}/userguide/tasks/incrementalTask/incrementalTaskRemovedOutput.out[]
   ----
  -
  -When a task input property is modified, Gradle is unable to determine how this property impacted the task outputs, so the task is executed non-incrementally.
  -So similar to the changed output file example, details for _all_ input files for the given property are returned by link:{groovyDslPath}/org.gradle.work.InputChanges.html#org.gradle.work.InputChanges:getFileChanges(org.gradle.api.file.FileCollection)[InputChanges.getFileChanges]:
  -
  -=== Example: Running the incremental task with an input property changed
  -
  -.Output of **`gradle -q -PtaskInputProperty=changed incrementalReverse`**
  +====
  +
  +The last scenario we want to cover concerns what happens when a non-file-based input property is modified.
  +In such cases, Gradle is unable to determine how the property impacts the task outputs, so the task is executed non-incrementally.
  +This means that _all_ input files for the given property are returned by link:{groovyDslPath}/org.gradle.work.InputChanges.html#org.gradle.work.InputChanges:getFileChanges(org.gradle.api.file.FileCollection)[InputChanges.getFileChanges()] and they are all treated as `ADDED`.
  +The following example sets the project property `taskInputProperty` to a new value when running the `incrementalReverse` task and that project property is used to initialize the task's `inputProperty` property, as you can see in the <<ex:incremental_task_definition,first example of this section>>.
  +Here's the output you can expect in this case:
  +
  +.Running the incremental task with an input property changed
  +====
  +.Output of `gradle -q -PtaskInputProperty=changed incrementalReverse`
   ----
   > gradle -q -PtaskInputProperty=changed incrementalReverse
   include::{samplesPath}/userguide/tasks/incrementalTask/incrementalTaskChangedProperty.out[]
   ----
  +====
   
   [[sec:storing_incremental_task_state]]
   === Storing incremental state for cached tasks
  
positive.code: This way when the task's results are loaded from cache, the next execution can already use the analysis data loaded from cache, too.
  
  However, if the state files are non-relocatable, then they can't be shared via the build cache.
  Indeed, when the task is loaded from cache, any such state files must be cleaned up to prevent stale state to confuse the tool during the next execution.
  Gradle can ensure such stale files are removed if they are declared via `task.localState.register()` or a property is marked with the `@LocalState` annotation.
  
  [[sec:declaring_and_using_command_line_options]]
  == Declaring and Using Command Line Options
  
negative.code: 
  NOTE: The code for this example can be found at **`samples/userguide/tasks/incrementalTask`** in the ‘-all’ distribution of Gradle.
  
  If for some reason the task is executed non-incrementally, for example by running with `--rerun-tasks`, all files are reported as `ADDED`, irrespective of the previous state.
  In this case, Gradle automatically removes the previous outputs, so the incremental task only needs to process the given files.
  
  For a simple transformer task like the above exmaple, the task action simply needs to generate output files for any out-of-date inputs and delete output files for any removed inputs.
  
  [IMPORTANT]
  ====
  A task may only contain a single incremental task action.
  ====
  
  [[sec:which_inputs_are_considered_out_of_date]]
  === Which inputs are considered out of date?
  
  When there is a previous execution of the task, and the only changes since that execution are to incremental input file properties, then Gradle is able to determine which input files need to be processed (incremental execution).
  In this case, the link:{groovyDslPath}/org.gradle.work.InputChanges.html#org.gradle.work.InputChanges:getFileChanges(org.gradle.api.file.FileCollection)[InputChanges.getFileChanges()] method returns details for all input files for the given property that were _added_, _modified_ or _removed_.
  
  However, there are many cases where Gradle is unable to determine which input files need to be processed (non-incremental execution).
  Examples include:
  
  * There is no history available from a previous execution.
  * You are building with a different version of Gradle. Currently, Gradle does not use task history from a different version.
  * An link:{javadocApi}/org/gradle/api/tasks/TaskOutputs.html#upToDateWhen-groovy.lang.Closure-[`upToDateWhen`] criterion added to the task returns `false`.
  * An input property has changed since the previous execution.
  * A non-incremental input file property has changed since the previous execution.
  * One or more output files have changed since the previous execution.
  
  In all of these cases, Gradle will report all input files as `ADDED` and the `getFileChanges()` method will return details for all the files that comprise the given input property.
  
  You can check if the task execution is incremental or not with the link:{groovyDslPath}/org.gradle.work.InputChanges.html#org.gradle.work.InputChanges.html##org.gradle.work.InputChanges:incremental[InputChanges.isIncremental()] method.
  
  [[sec:an_incremental_task_in_action]]
  === An incremental task in action
  
  Given the example incremental task implementation <<#taskDefinition,above>>, let's walk through some scenarios based on it.
  
  First, consider an instance of `IncrementalReverseTask` that is executed against a set of inputs for the first time.
  In this case, all inputs will be considered added, as shown here:
  
  [[ex:incremental_task_definition]]
  .Running the incremental task for the first time
  ====
  include::sample[dir="userguide/tasks/incrementalTask/groovy",files="build.gradle[tags=reverse]"]
  include::sample[dir="userguide/tasks/incrementalTask/kotlin",files="build.gradle.kts[tags=reverse]"]
  
  .Build layout
  ----
  