Working With Files

The ProjectLayout class is used to access various directories and files within a project. It provides methods to retrieve paths to the project directory, build directory, settings file, and other important locations within the project’s file structure. This class is particularly useful when you need to work with files in a build script or plugin in different project paths:

You can learn more about the ProjectLayout class in Services.

Gradle provides the Project.file(java.lang.Object) method for specifying the location of a single file or directory.

Relative paths are resolved relative to the project directory, while absolute paths remain unchanged.

Here are some examples of using the file() method with different types of arguments:

As you can see, you can pass strings, File instances and Path instances to the file() method, all of which result in an absolute File object.

In the case of multi-project builds, the file() method will always turn relative paths into paths relative to the current project directory, which may be a child project.

Suppose you want to use a path relative to the root project directory. In that case, you need to use the special Project.getRootDir() property to construct an absolute path, like so:

Let’s say you’re working on a multi-project build in the directory: dev/projects/AcmeHealth.
The build script above is at: AcmeHealth/subprojects/AcmePatientRecordLib/build.gradle.
The file path will resolve to the absolute of: dev/projects/AcmeHealth/shared/config.xml.

Note that Project also provides Project.getRootProject() for multi-project builds which, in the example, would resolve to: dev/projects/AcmeHealth/subprojects/AcmePatientRecordLib.

A file collection is simply a set of file paths represented by the FileCollection interface.

The set of paths can be any file path. The file paths don’t have to be related in any way, so they don’t have to be in the same directory or have a shared parent directory.

The recommended way to specify a collection of files is to use the ProjectLayout.files(java.lang.Object...) method, which returns a FileCollection instance. This flexible method allows you to pass multiple strings, File instances, collections of strings, collections of Files, and more. You can also pass in tasks as arguments if they have defined outputs.

As with the Project.file(java.lang.Object) method covered in the previous section, all relative paths are evaluated relative to the current project directory. The following example demonstrates some of the variety of argument types you can use — strings, File instances, lists, or Paths:

File collections have important attributes in Gradle. They can be:

Lazy creation of a file collection is useful when evaluating the files that make up a collection when a build runs. In the following example, we query the file system to find out what files exist in a particular directory and then make those into a file collection:

The key to lazy creation is passing a closure (in Groovy) or a Provider (in Kotlin) to the files() method. Your closure or provider must return a value of a type accepted by files(), such as List<File>, String, or FileCollection.

Iterating over a file collection can be done through the each() method (in Groovy) or forEach method (in Kotlin) on the collection or using the collection in a for loop. In both approaches, the file collection is treated as a set of File instances, i.e., your iteration variable will be of type File.

The following example demonstrates such iteration. It also demonstrates how you can convert file collections to other types using the as operator (or supported properties):

You can also see at the end of the example how to combine file collections using the + and - operators to merge and subtract them. An important feature of the resulting file collections is that they are live. In other words, when you combine file collections this way, the result always reflects what’s currently in the source file collections, even if they change during the build.

For example, imagine collection in the above example gains an extra file or two after union is created. As long as you use union after those files are added to collection, union will also contain those additional files. The same goes for the different file collection.

Live collections are also important when it comes to filtering. Suppose you want to use a subset of a file collection. In that case, you can take advantage of the FileCollection.filter(org.gradle.api.specs.Spec) method to determine which files to "keep". In the following example, we create a new collection that consists of only the files that end with .txt in the source collection:

If collection changes at any time, either by adding or removing files from itself, then textFiles will immediately reflect the change because it is also a live collection. Note that the closure you pass to filter() takes a File as an argument and should return a boolean.

Many objects in Gradle have properties which accept a set of input files. For example, the JavaCompile task has a source property that defines the source files to compile. You can set the value of this property using any of the types supported by the files() method, as mentioned in the API docs. This means you can, for example, set the property to a File, String, collection, FileCollection or even a closure or Provider.

This is a feature of specific tasks! That means implicit conversion will not happen for just any task that has a FileCollection or FileTree property. If you want to know whether implicit conversion happens in a particular situation, you will need to read the relevant documentation, such as the corresponding task’s API docs. Alternatively, you can remove all doubt by explicitly using ProjectLayout.files(java.lang.Object...) in your build.

Here are some examples of the different types of arguments that the source property can take:

One other thing to note is that properties like source have corresponding methods in core Gradle tasks. Those methods follow the convention of appending to collections of values rather than replacing them. Again, this method accepts any of the types supported by the files() method, as shown here:

As this is a common convention, we recommend that you follow it in your own custom tasks. Specifically, if you plan to add a method to configure a collection-based property, make sure the method appends rather than replaces values.

A file tree is a file collection that retains the directory structure of the files it contains and has the type FileTree. This means all the paths in a file tree must have a shared parent directory. The following diagram highlights the distinction between file trees and file collections in the typical case of copying files:

The simplest way to create a file tree is to pass a file or directory path to the Project.fileTree(java.lang.Object) method. This will create a tree of all the files and directories in that base directory (but not the base directory itself). The following example demonstrates how to use this method and how to filter the files and directories using Ant-style patterns:

You can see more examples of supported patterns in the API docs for PatternFilterable.

By default, fileTree() returns a FileTree instance that applies some default exclude patterns for convenience — the same defaults as Ant. For the complete default exclude list, see the Ant manual.

If those default excludes prove problematic, you can work around the issue by changing the default excludes in the settings script:

You can do many of the same things with file trees that you can with file collections:

You can also traverse file trees using the FileTree.visit(org.gradle.api.Action) method. All of these techniques are demonstrated in the following example:

CopySpec is a copy specification that allows you to define what files to copy, where to copy them from, and where to copy them. It provides a flexible and expressive way to specify complex file copying operations, including filtering files based on patterns, renaming files, and including/excluding files based on various criteria.

CopySpec instances are used in the Copy task to specify the files and directories to be copied.

CopySpec has two important attributes:

The Sync task, which extends the Copy task, copies the source files into the destination directory and then removes any files from the destination directory which it did not copy. It synchronizes the contents of a directory with its source.

This can be useful for doing things such as installing your application, creating an exploded copy of your archives, or maintaining a copy of the project’s dependencies.

Here is an example that maintains a copy of the project’s runtime dependencies in the build/libs directory:

You can also perform the same function in your own tasks with the Project.sync(org.gradle.api.Action) method.

You can copy a file by creating an instance of Gradle’s builtin Copy task and configuring it with the location of the file and where you want to put it.

This example mimics copying a generated report into a directory that will be packed into an archive, such as a ZIP or TAR:

The file and directory paths are then used to specify what file to copy using Copy.from(java.lang.Object…​) and which directory to copy it to using Copy.into(java.lang.Object).

Although hard-coded paths make for simple examples, they make the build brittle. Using a reliable, single source of truth, such as a task or shared project property, is better. In the following modified example, we use a report task defined elsewhere that has the report’s location stored in its outputFile property:

We have also assumed that the reports will be archived by archiveReportsTask, which provides us with the directory that will be archived and hence where we want to put the copies of the reports.

You can extend the previous examples to multiple files very easily by providing multiple arguments to from():

Two files are now copied into the archive directory.

You can also use multiple from() statements to do the same thing, as shown in the first example of the section File copying in depth.

But what if you want to copy all the PDFs in a directory without specifying each one? To do this, attach inclusion and/or exclusion patterns to the copy specification. Here, we use a string pattern to include PDFs only:

One thing to note, as demonstrated in the following diagram, is that only the PDFs that reside directly in the reports directory are copied:

You can include files in subdirectories by using an Ant-style glob pattern (**/*), as done in this updated example:

This task has the following effect:

Remember that a deep filter like this has the side effect of copying the directory structure below reports and the files. If you want to copy the files without the directory structure, you must use an explicit fileTree(dir) { includes }.files expression.

You may need to copy files as well as the directory structure in which they reside. This is the default behavior when you specify a directory as the from() argument, as demonstrated by the following example that copies everything in the reports directory, including all its subdirectories, to the destination:

The key aspect that users need help with is controlling how much of the directory structure goes to the destination. In the above example, do you get a toArchive/reports directory, or does everything in reports go straight into toArchive? The answer is the latter. If a directory is part of the from() path, then it won’t appear in the destination.

So how do you ensure that reports itself is copied across, but not any other directory in ${layout.buildDirectory}? The answer is to add it as an include pattern:

You’ll get the same behavior as before except with one extra directory level in the destination, i.e., toArchive/reports.

One thing to note is how the include() directive applies only to the from(), whereas the directive in the previous section applied to the whole task. These different levels of granularity in the copy specification allow you to handle most requirements that you will come across easily.

The basic process of copying files in Gradle is a simple one:

But this apparent simplicity hides a rich API that allows fine-grained control of which files are copied, where they go, and what happens to them as they are copied — renaming of the files and token substitution of file content are both possibilities, for example.

Let’s start with the last two items on the list, which involve CopySpec. The CopySpec interface, which the Copy task implements, offers:

CopySpec has several additional methods that allow you to control the copying process, but these two are the only required ones. into() is straightforward, requiring a directory path as its argument in any form supported by the Project.file(java.lang.Object) method. The from() configuration is far more flexible.

Not only does from() accept multiple arguments, it also allows several different types of argument. For example, some of the most common types are:

In fact, from() accepts all the same arguments as Project.files(java.lang.Object…​) so see that method for a more detailed list of acceptable types.

Something else to consider is what type of thing a file path refers to:

Here is an example that uses multiple from() specifications, each with a different argument type. You will probably also notice that into() is configured lazily using a closure (in Groovy) or a Provider (in Kotlin) — a technique that also works with from():

Note that the lazy configuration of into() is different from a child specification, even though the syntax is similar. Keep an eye on the number of arguments to distinguish between them.

Occasionally, you want to copy files or directories as part of a task. For example, a custom archiving task based on an unsupported archive format might want to copy files to a temporary directory before they are archived. You still want to take advantage of Gradle’s copy API without introducing an extra Copy task.

The solution is to use the Project.copy(org.gradle.api.Action) method. Configuring it with a copy spec works like the Copy task. Here’s a trivial example:

The above example demonstrates the basic syntax and also highlights two major limitations of using the copy() method:

The following example shows how to work around these limitations using the dynamic API for task inputs and outputs:

These limitations make it preferable to use the Copy task wherever possible because of its built-in support for incremental building and task dependency inference. That is why the copy() method is intended for use by custom tasks that need to copy files as part of their function. Custom tasks that use the copy() method should declare the necessary inputs and outputs relevant to the copy action.

If the files used and generated by your builds sometimes don’t have names that suit, you can rename those files as you copy them. Gradle allows you to do this as part of a copy specification using the rename() configuration.

The following example removes the "-staging" marker from the names of any files that have it:

As in the above example, you can use regular expressions for this or closures that use more complex logic to determine the target filename. For example, the following task truncates filenames:

As with filtering, you can also rename a subset of files by configuring it as part of a child specification on a from().

The example of how to rename files on copy gives you most of the information you need to perform this operation. It demonstrates the two options for renaming:

Regular expressions are a flexible approach to renaming, particularly as Gradle supports regex groups that allow you to remove and replace parts of the source filename. The following example shows how you can remove the string "-staging" from any filename that contains it using a simple regular expression:

You can use any regular expression supported by the Java Pattern class and the substitution string. The second argument of rename() works on the same principles as the Matcher.appendReplacement() method.

The closure syntax for rename() is straightforward and can be used for any requirements that simple regular expressions can’t handle. You’re given a file’s name, and you return a new name for that file or null if you don’t want to change the name. Be aware that the closure will be executed for every file copied, so try to avoid expensive operations where possible.

You can apply filtering in any copy specification through the CopySpec.include(java.lang.String…​) and CopySpec.exclude(java.lang.String…​) methods.

These methods are typically used with Ant-style include or exclude patterns, as described in PatternFilterable.

You can also perform more complex logic by using a closure that takes a FileTreeElement and returns true if the file should be included or false otherwise. The following example demonstrates both forms, ensuring that only .html and .jsp files are copied, except for those .html files with the word "DRAFT" in their content:

A question you may ask yourself at this point is what happens when inclusion and exclusion patterns overlap? Which pattern wins? Here are the basic rules:

Bear these rules in mind when creating combined inclusion and exclusion specifications so that you end up with the exact behavior you want.

Note that the inclusions and exclusions in the above example will apply to all from() configurations. If you want to apply filtering to a subset of the copied files, you’ll need to use child specifications.

Transforming the content of files while they are being copied involves basic templating that uses token substitution, removal of lines of text, or even more complex filtering using a full-blown template engine.

The following example demonstrates several forms of filtering, including token substitution using the CopySpec.expand(java.util.Map) method and another using CopySpec.filter(java.lang.Class) with an Ant filter:

The filter() method has two variants, which behave differently:

Note that both variants assume the source files are text-based. When you use the ReplaceTokens class with filter(), you create a template engine that replaces tokens of the form @tokenName@ (the Ant-style token) with values you define.

The expand() method treats the source files as Groovy templates, which evaluates and expands expressions of the form ${expression}.

You can pass in property names and values that are then expanded in the source files. expand() allows for more than basic token substitution as the embedded expressions are full-blown Groovy expressions.

For any CopySpec involved in copying files, may it be the Copy task itself, or any child specifications, you can explicitly set the permissions the destination files will have via the CopySpec.filePermissions {} configurations block.

You can do the same for directories too, independently of files, via the CopySpec.dirPermissions {} configurations block.

For a detailed description of file permissions, see FilePermissions and UserClassFilePermissions. For details on the convenience method used in the samples, see ConfigurableFilePermissions.unix(String).

Using empty configuration blocks for file or directory permissions still sets them explicitly, just to fixed default values. Everything inside one of these configuration blocks is relative to the default values. Default permissions differ for files and directories:

File.renameTo() is a method in Java (and by extension, in Gradle’s Groovy DSL) used to rename or move a file or directory. When you call renameTo() on a File object, you provide another File object representing the new name or location. If the operation is successful, renameTo() returns true; otherwise, it returns false.

It’s important to note that renameTo() has some limitations and platform-specific behavior.

In this example, the moveFile task uses the Copy task type to specify the source and destination directories. Inside the doLast closure, it uses File.renameTo() to move the file from the source directory to the destination directory:

In this example, the moveFile task copies the file source.txt to the destination directory and renames it to new_name.txt in the process. This achieves a similar effect to moving a file.

You can easily delete files and directories using the Delete task. You must specify which files and directories to delete in a way supported by the Project.files(java.lang.Object…​) method.

For example, the following task deletes the entire contents of a build’s output directory:

If you want more control over which files are deleted, you can’t use inclusions and exclusions the same way you use them for copying files. Instead, you use the built-in filtering mechanisms of FileCollection and FileTree. The following example does just that to clear out temporary files from a source directory:

The Project.delete(org.gradle.api.Action) method can delete files and directories.

This method takes one or more arguments representing the files or directories to be deleted.

For example, the following task deletes the entire contents of a build’s output directory:

If you want more control over which files are deleted, you can’t use inclusions and exclusions the same way you use them for copying files. Instead, you use the built-in filtering mechanisms of FileCollection and FileTree. The following example does just that to clear out temporary files from a source directory:

The simplest case involves archiving the entire contents of a directory, which this example demonstrates by creating a ZIP of the toArchive directory:

Notice how we specify the destination and name of the archive instead of an into(): both are required. You often won’t see them explicitly set because most projects apply the Base Plugin. It provides some conventional values for those properties.

The following example demonstrates this; you can learn more about the conventions in the archive naming section.

Each type of archive has its own task type, the most common ones being Zip, Tar and Jar. They all share most of the configuration options of Copy, including filtering and renaming.

One of the most common scenarios involves copying files into specified archive subdirectories. For example, let’s say you want to package all PDFs into a docs directory in the archive’s root. This docs directory doesn’t exist in the source location, so you must create it as part of the archive. You do this by adding an into() declaration for just the PDFs:

As you can see, you can have multiple from() declarations in a copy specification, each with its own configuration. See Using child copy specifications for more information on this feature.

Archives are essentially self-contained file systems, and Gradle treats them as such. This is why working with archives is similar to working with files and directories.

Out of the box, Gradle supports the creation of ZIP and TAR archives and, by extension, Java’s JAR, WAR, and EAR formats—Java’s archive formats are all ZIPs. Each of these formats has a corresponding task type to create them: Zip, Tar, Jar, War, and Ear. These all work the same way and are based on copy specifications, just like the Copy task.

Creating an archive file is essentially a file copy in which the destination is implicit, i.e., the archive file itself. Here is a basic example that specifies the path and name of the target archive file:

The full power of copy specifications is available to you when creating archives, which means you can do content filtering, file renaming, or anything else covered in the previous section. A common requirement is copying files into subdirectories of the archive that don’t exist in the source folders, something that can be achieved with into() child specifications.

Gradle allows you to create as many archive tasks as you want, but it’s worth considering that many convention-based plugins provide their own. For example, the Java plugin adds a jar task for packaging a project’s compiled classes and resources in a JAR. Many of these plugins provide sensible conventions for the names of archives and the copy specifications used. We recommend you use these tasks wherever you can rather than overriding them with your own.

Gradle has several conventions around the naming of archives and where they are created based on the plugins your project uses. The main convention is provided by the Base Plugin, which defaults to creating archives in the layout.buildDirectory.dir("distributions") directory and typically uses archive names of the form [projectName]-[version].[type].

The following example comes from a project named archive-naming, hence the myZip task creates an archive named archive-naming-1.0.zip:

Note that the archive name does not derive from the task’s name that creates it.

If you want to change the name and location of a generated archive file, you can provide values for the corresponding task’s archiveFileName and destinationDirectory properties. These override any conventions that would otherwise apply.

Alternatively, you can make use of the default archive name pattern provided by AbstractArchiveTask.getArchiveFileName(): [archiveBaseName]-[archiveAppendix]-[archiveVersion]-[archiveClassifier].[archiveExtension]. You can set each of these properties on the task separately. Note that the Base Plugin uses the convention of the project name for archiveBaseName, project version for archiveVersion, and the archive type for archiveExtension. It does not provide values for the other properties.

This example — from the same project as the one above — configures just the archiveBaseName property, overriding the default value of the project name:

You can also override the default archiveBaseName value for all the archive tasks in your build by using the project property archivesBaseName, as demonstrated by the following example:

You can find all the possible archive task properties in the API documentation for AbstractArchiveTask. Still, we have also summarized the main ones here:

As described in the CopySpec section above, you can use the Project.copySpec(org.gradle.api.Action) method to share content between archives.

An archive is a directory and file hierarchy packed into a single file. In other words, it’s a special case of a file tree, and that’s exactly how Gradle treats archives.

Instead of using the fileTree() method, which only works on normal file systems, you use the Project.zipTree(java.lang.Object) and Project.tarTree(java.lang.Object) methods to wrap archive files of the corresponding type (note that JAR, WAR and EAR files are ZIPs). Both methods return FileTree instances that you can then use in the same way as normal file trees. For example, you can extract some or all of the files of an archive by copying its contents to some directory on the file system. Or you can merge one archive into another.

Here are some simple examples of creating archive-based file trees:

You can see a practical example of extracting an archive file in the unpacking archives section below.

Sometimes it’s desirable to recreate archives exactly the same, byte for byte, on different machines. You want to be sure that building an artifact from source code produces the same result no matter when and where it is built. This is necessary for projects like reproducible-builds.org.

Reproducing the same byte-for-byte archive poses some challenges since the order of the files in an archive is influenced by the underlying file system. Each time a ZIP, TAR, JAR, WAR or EAR is built from source, the order of the files inside the archive may change. Files that only have a different timestamp also causes differences in archives from build to build.

All AbstractArchiveTask (e.g. Jar, Zip) tasks shipped with Gradle include support for producing reproducible archives.

For example, to make a Zip task reproducible you need to set Zip.isReproducibleFileOrder() to true and Zip.isPreserveFileTimestamps() to false. In order to make all archive tasks in your build reproducible, consider adding the following configuration to your build file:

Often you will want to publish an archive, so that it is usable from another project.

The two functions of interest are Project.zipTree(java.lang.Object) and Project.tarTree(java.lang.Object), which produce a FileTree from a corresponding archive file.

That file tree can then be used in a from() specification, like so:

As with a normal copy, you can control which files are unpacked via filters and even rename files as they are unpacked.

More advanced processing can be handled by the eachFile() method. For example, you might need to extract different subtrees of the archive into different paths within the destination directory. The following sample uses the method to extract the files within the archive’s libs directory into the root destination directory, rather than into a libs subdirectory:

If you’re a Java developer wondering why there is no jarTree() method, that’s because zipTree() works perfectly well for JARs, WARs, and EARs.

Gradle does not have full built-in support for creating uber JARs, but you can use third-party plugins like the Shadow plugin (com.gradleup.shadow) to achieve this. This plugin packages your project classes and dependencies into a single JAR file.

To copy the contents of other JAR files into the application JAR, use the Project.zipTree(java.lang.Object) method and the Jar task. This is demonstrated by the uberJar task in the following example:

In this case, we’re taking the runtime dependencies of the project — configurations.runtimeClasspath.files — and wrapping each of the JAR files with the zipTree() method. The result is a collection of ZIP file trees, the contents of which are copied into the uber JAR alongside the application classes.

In cases where you need to create a directory manually, you can use the standard Files.createDirectories or File.mkdirs methods from within your build scripts or custom task implementations.

Here is a simple example that creates a single images directory in the project folder:

As described in the Apache Ant manual, the mkdir task will automatically create all necessary directories in the given path. It will do nothing if the directory already exists.

You can create directories in Gradle using the mkdir method, which is available in the Project object. This method takes a File object or a String representing the path of the directory to be created:

You can use a Copy task to install the executable into shared directories like /usr/local/bin. The installation directory probably contains many other executables, some of which may even be unreadable by Gradle. To support the unreadable files in the Copy task’s destination directory and to avoid time consuming up-to-date checks, you can use Task.doNotTrackState():

When working with application servers, you can use a Copy task to deploy the application archive (e.g. a WAR file). Since you are deploying a single file, the destination directory of the Copy is the whole deployment directory. The deployment directory sometimes does contain unreadable files like named pipes, so Gradle may have problems doing up-to-date checks. In order to support this use-case, you can use Task.doNotTrackState():