How to restore incremental state for a cached task?

Also asked on caching - Gradle: How to restore incremental state for a cached task? - Stack Overflow Please answer on stackoverflow, to keep it a single source of truth.

I want to cache and reuse analysis data from a previous run of the build. Specifically, the assets and dependency graph files in multiple obj folders across a workspace, to levrage incremental nuget restore - but this can be generalized.

I’m using gradle 7.2. From the docs at Developing Custom Gradle Task Types

Storing incremental state for cached tasks

Using Gradle’s InputChanges is not the only way to create tasks that only work on changes since the last execution. Tools like the Kotlin compiler provide incrementality as a built-in feature. The way this is typically implemented is that the tool stores some analysis data about the state of the previous execution in some file. If such state files are relocatable, then they can be declared as outputs of the task. This way when the task’s results are loaded from cache, the next execution can already use the analysis data loaded from cache, too.

From this paragraph I understand that gradle can cache the relevant files for me if I mark them as output.files(), and I can then feed them to the build task the next time it runs.

How can I restore the cached intermediate output files from a previous run to the next?

Here’s a simplified attempt to see if I can get past output to restore under the current build:

task clean(type: Delete) {
    delete buildDir
}

task testTheory {
    outputs.files(fileTree(dir: buildDir, include: "*.txt"))
    outputs.cacheIf { true }

    doLast {
        def outFile = file("$buildDir/test${new Date().format("HH-mm-ss")}.txt")
        if(!outFile.exists()) {
            outFile.parentFile.mkdirs()
        }
        outFile.withWriter("UTF-8") { writer ->
            writer << new Date() << System.lineSeparator()
        }
    }
}

My goal is after running

gradle testTheory testTheory
gradle testTheory clean testTheory

to have multiple files in the build folder.

One idea is to manually move the files to a cache I manage myself, but the docs seem to suggest a proper gradle way of doing things, and I’d like to try that first.

One concern even if the cache works is that it may take a long time for the files to be copied to the cache and back.