I see that the PathSensitivity enum has a NONE case, which is documented as:
Ignore file paths and directories altogether.
Seeing as there is also a NAME_ONLY case, I must assume that the entire path name must therefore be irrelevant for any @InputFile, @InputFiles or @InputDirectory annotated as having PathSensitivity.NONE. which seems rather odd for a file or a directory input:
“Yes, your task’s inputs are now coming from over here rather than other there, but you still don’t need to re-execute…”
Have I understood this correctly please? When would I need to use this feature?
Thanks,
Chris
Yes, you did understand that correctly. A use-case is a configuration file where the task only cares about the contents of the file and not about the file location at all.
Thanks for replying. So for a FileCollection, would Gradle compute the hash of every single input (every single time) and then re-execute the task if the set were different in any way?
This approach sounds “expensive” for large files . Presumably it’s not intended for jars then?
The same computation is necessary either way, otherwise Gradle would not see the file changed, it does not rely on file change dates with is an unreliable measure. The difference is just whether the path of a part of it is significant too, additional to the file contents.
OK, thanks. My difficulty here is that files in my build tend to have known names and locations, and so I’ve never had any need for anything other than RELATIVE. (And only then because the default PathSensitivity is ABSOLUTE.) Even now, the use-case for NONE seems to be “Using an @InputFile that the build has generated using File.createTempFile().”
No, the use-case for NONE is, if neither the file path nor the file name is significant but only the file content.
If your build reads a file and generates something from the contents without considering how the file is named or where it is stored, then the path and name are pointless and don’t need to make the task re-run.
If you for example have a file version.properties with content
version = 1.2.3
and you have a task that takes this file as input and produces a file Version.java with content
public class Version {
public static String version = "1.2.3";
}
Now if you rename the file version.properties to something else or move it around in the filesystem, that will in no way influence the result of the task, so what you want is NONE path sensitivity, because as long as a file with the same content is given as input, the task can stay up-to-date.
OK thanks. But (umm) I don’t do that (and I especially don’t gratuitously rename files or move them around willy-nilly on build machines ). To be blunt, I’d still put version.properties into a known location so that while its path name may be irrelevant, it would also be both known and constant. Maybe Gradle could save an extra pair of femtoseconds by not checking something that would never change, but so what?
But anyway, thanks for explaining this feature. I do at least understand it now, even if I currently have no use for it.
Cheers,
Chris
It’s not really the point whether you intend to move files around or not on CI.
For example imagine that you move the file during a refactoring to a different place but the content stays the same.
Then every time you switch between a branch where it is moved and where it is not moved, the task will be out-of-date unnecessarily.
Or if you use the build output cache which is also based on the inputs and outputs, you can reuse a cache entry in more cases.
It is totally okay to not use NONE, all that happens is, that you get unnecessary out-of-dates or cache misses when the whole work of the task could have been skipped but cannot.
It’s exactly the same for RELATIVE vs. ABSOLUTE. If you use ABSOLUTE everywhere the cache key is bound to the exact paths, so entries cannot be reused across different worktrees or even machines that do not have the files in the exact same location.
So basically said, as long as you don’t use the build cache, the path sensitivity is of little relevance, it could only save you one task execution when you actually move the file. But if you develop a task for which it is worth to make it cacheable, it should also be worth to consider the right PathSensitivity so that a cache entry can be reused as often as possible.
. Presumably it’s not intended for jars then?
…
). To be blunt, I’d still put 