File Utilities

The FileSystemOperations object has many methods to work with files and directories

An instance of it can be obtained via ConfigCacheSafeOptions.fsOperations() or ProjectOperations.getFsOperations(). This instance is configuration cache compatible and can be called from within a task action.

Recursive evaluation

Some conversion methods take an Object instance of a collection of Object as inputs. They can recursively unpack Callable, Closure, Optional, Provider and Supplier until it gets to something it can evaluate.

Conversions

You are probably familiar with project.file to convert a single object to a file. Grolifant offers similar, but more powerful methods. There are also methods that take a collection of objects and convert them to a list of files.

Supported types

Any CharSequence
java.io.File and java.nio.file.Path
URIs of scheme file:.
org.gradle.api.file.Directory
org.gradle.api.file.RegularFile
org.gradle.api.resources.TextResource
org.gradle.api.file.FileCollection
Any wrapper described aboce such as Provider

Methods

file(Object) - Converts a single object to a file.
fileOrNull(Object) - Similar to file, but allows for null to be passed.
files(Collection<Object>)> - Take a collection of objects and convert them to files. Any item in the collection that is a null will result in an exception being emitted.
filesDropNull(Collection<Object>) - Take a collection of objects and convert them to files. Any null entries will be removed from the final result.
provideFile(Object) - Create a File provider to a lazy-evaluated object.
provideRegularFile(Object) - Create a RegularFile provider to a lazy-evaluated object.
provideDirectory(Object) - Create a Directory provider to a lazy-evaluated object.

CopySpec(s)

Creating an empty CopySpec

Use copySpec to create an empty CopySpec.

Resolving a CopySpec to files

Sometimes one wants to use a org.gradle.api.file.CopySpec as part of a DSL, but resolve it to a file collection without performing a copy or synchronisation. There is one method available to do so - resolveFilesFromCopySpec. It returns a FileTree.

Copy, delete and sync operations

These ensure the old project.copy and project.sync works across Gradle API releases. They can be called from within task actions.

Methods

copy - Executes a copy specification into a specific directory.
delete - Deletes all the specified files and directories.
sync - Execution a synchronisation into a specific directory using a specification.

Creating safe filenames

Sometimes you might want to use entities such as task names in file names. Use the toSafeFilename method to obtain a string that can be used as part of a filename.

In similar fashion you can concatenate a number of subpaths and ensure that the resulting path only consists of safe file names. There are two methods for this.

toSafePath(String…) - Creates a Path instance.
toSafeFile(String…) - Creates a File instance.

File collections

Methods

emptyFileCollection - Return a configurable empty file collection.
fileTree - A CondifugrableFileTree instance staring at the provided starting point. Anything convertible with file(Object) will suffice as input.

File locations

Obtaining a subfolder of the build directory

Use the buildDirDescendant method, which returns a provider to a File.
Use the buildDirRegularFile method, which returns a provider to a RegularFile.
Use the buildDirDirectory method, which returns a provider to a Directory.

Anything that can be evaluated to a string using StringTools can be passed as a parameter.

fsOperations().buildDirDescendant('docs/asciidoc')

Project cache directory

If a plugin might need to cache information in the local cache directory it is important that it determines this folder correctly.

You can call getProjectCacheDir to achieve this.

You can also use it in provider form - provideProjectCacheDir to achieve this.

If you want to get a directory below the cache directory then use provideProjectCacheDirDescendant.

Gradle distribution directory

getGradleHomeDir will provide the home of the currently active Gradle distribution.

Gradle user home directory

getGradleUserHomeDir will provide the currently active home directory for the user.

Project directory

Use getProjectDir to obtain the directory of the current (sub)project.

You can also get it in Provider form - provideProjectDir.

Project root directory

Use getProjectRootDir to obtain the root directory of the current (sub)project.

You can also get it in Provider form - provideRootDir

Listing child directories of a directory

listDirs provides a list of child directories of a directory.

Resolving a TAR or ZIP to files.

Methods

tarTree - For Tar archives. zipTree - For Zip archives.

Both meotds can be passed an object that can be converted using the earlier mentioned file method.

Readable compression resources

If you have a file that is BZIP2 or GZ comrpessed, you can easily create a org.gradle.api.resources.ReadableResource from it.

Methods

bzip2Resource(Object) - BZIP2 resources
gzipResource(Object) - GZIP resources

Anything convertible to a file using the earlier mentioned conversion methods, can be passed as parameter.

Relative paths

Relative paths can be very useful in many cases.

Methods

relativePath - The relative path FROM the project directory to the given path
relativePathNotEmpty - Similar to relativePath, but if the two entities are siblings, return . rather than an empty string.
relativeRootPath - The relative path FROM the root project directory to the given path.
relativePathToProjectDir - The relative path from the given path to the project directory.
relativePathToRootDir - The relative path from the given path to the root project directory.
relativize - For two instances return the relative path of a target from a base i.e. the path to traverse starting at the base file. One version of this method takes two File instances and another two Path instances.

Resolving the location of a class

For some cases it is handy to resolve the location of a class, so that it can be added to a classpath. One use case is the for javaexec processes and Gradle workers. Use resolveClassLocation to obtain a File object to the class. If the class is located in a JAR it path to the JAR will be returned. If the class is directly on the filesystem, the toplevel directory for the package hierarchy that the class belongs to, will be returned.

Resource Files

There are a number of methods to simplify loading content from resource files.

Methods

copyResourceToFile - Copy a file at a resource path to a destination file.
loadPropertiesFromResource - Load the properties file at the given resource path.
providePropertiesFromResource - Load the properties file at the given resource path only on-demand.

There a versions of the above which also allow for specifying the class loader.

Resources from URLs

It is possible to declare single files via http and file resources. These are meant to cache files from the internet. They are not intended to be used for larger artifacts such as ZIPs. As such, a typical use case might be downloading a JSON or a YAML file.

Use fileResource. There is a second variation which allows customisation of the file resource before download. Resources created this way are only downloaded on demand and cached. The default lifetime is 24h, but the value can be adjusted at creation time.

Temporary directories

createTempDirectory will create a temporary directory within the build directory.

Updating a File property

You can also update any Property<File> using the updateFileProperty utility method.