18

Working With Files

Most builds work with files. Gradle adds some concepts and APIs to help you achieve this.

18.1. Locating files

You can locate a file relative to the project directory using the Project.file() method.

Example 18.1. Locating files

build.gradle

// Using a relative path

File configFile = file('src/config.xml')

// Using an absolute path

configFile = file(configFile.absolutePath)

// Using a File object with a relative path configFile = file(new File('src/config.xml'))

You can pass any object to the file() method, and it will attempt to convert the value to an absolute File object. Usually, you would pass it a String or File instance. The supplied object'stoString() value is used as the file path. If this path is an absolute path, it is used to construct a File instance. Otherwise, a File instance is constructed by prepending the project directory path to the supplied path. The file() method also understands URLs, such as file:/s

.

Using this method is a useful way to convert some user provided value into an absolute File. It is preferable to using new File(somePath), as file() always evaluates the supplied path relative to the project directory, which is fixed, rather than the current working directory, which can change depending on how the user runs Gradle.

Page 99 of 343

18.2. File collections

A file collection is simply a set of files. It is represented by the FileCollection interface. Many objects in the Gradle API implement this interface. For example, dependency configurations implement FileCollection.

One way to obtain a FileCollection instance is to use the Project.files() method. You can pass this method any number of objects, which are then converted into a set of File objects. The files() method accepts any type of object as its parameters. These are evaluated relative to the project directory, as for the file() method, described in Section 18.1, “Locating files”.You can also pass collections, iterables, maps and arrays to the files() method. These are flattened and the contents converted to File instances.

Example 18.2. Creating a file collection

build.gradle

FileCollection collection = files('src/file1.txt', new File('src/file2.txt'),

A file collection is iterable, and can be converted to a number of other types using the as operator. You can also add 2 file collections together using the + operator, or subtract one file collection from another using the - operator. Here are some examples of what you can do with a file collection.

Example 18.3. Using a file collection

build.gradle

//Iterate over the files in the collection collection.each {File file ->

println file.name

}

//Convert the collection to various types Set set = collection.files

Set set2 = collection as Set List list = collection as List String path = collection.asPath File file = collection.singleFile File file2 = collection as File

//Add and subtract collections

def union = collection + files('src/file3.txt') def different = collection - files('src/file3.txt')

You can also pass the files() method a closure or a Callable instance. This is called when the contents of the collection are queried, and its return value is converted to a set of File instances. The return value can be an object of any of the types supported by the files() method. This is a simple way to 'implement' theFileCollection interface.

Page 100 of 343

Example 18.4. Implementing a file collection

build.gradle

task list << { File srcDir

// Create a file collection using a closure collection = files { srcDir.listFiles() }

srcDir = file('src')

println "Contents of $srcDir.name"

collection.collect { relativePath(it) }.sort().each { println it }

srcDir = file('src2')

println "Contents of $srcDir.name"

collection.collect { relativePath(it) }.sort().each { println it }

}

Output of gradle -q list

> gradle -q list Contents of src src/dir1 src/file1.txt Contents of src2 src2/dir1 src2/dir2

Some other types of things you can pass to files():

FileCollection

These are flattened and the contents included in the file collection.

Task

The output files of the task are included in the file collection.

TaskOutputs

The output files of the TaskOutputs are included in the file collection.

It is important to note that the content of a file collection is evaluated lazily, when it is needed. This means you can, for example, create a FileCollection that represents files which will be created in the future by, say, some task.

18.3. File trees

A file tree is a collection of files arranged in a hierarchy. For example, a file tree might represent a directory tree or the contents of a ZIP file. It is represented by the FileTree interface. The FileT interface extends FileCollection, so you can treat a file tree exactly the same way as you would a file collection. Several objects in Gradle implement the FileTree interface, such as sourc

.

One way to obtain a FileTree instance is to use the Project.fileTree() method. This

Page 101 of 343

creates a FileTree defined with a base directory, and optionally some Ant-style include and

exclude patterns.

Example 18.5. Creating a file tree

build.gradle

//Create a file tree with a base directory FileTree tree = fileTree(dir: 'src/main')

//Add include and exclude patterns to the tree tree.include '**/*.java'

tree.exclude '**/Abstract*'

//Create a tree using path

tree = fileTree('src').include('**/*.java')

//Create a tree using closure tree = fileTree('src') {

include '**/*.java'

}

//Create a tree using a map

tree = fileTree(dir:		'src', include: '**/*.java')
tree =	fileTree(dir:	'src',	includes: ['**/*.java', '**/*.xml'])
tree =	fileTree(dir:	'src',	include: '**/*.java', exclude: '**/*test*/**')

You use a file tree in the same way you use a file collection. You can also visit the contents of the tree, and select a sub-tree using Ant-style patterns:

Example 18.6. Using a file tree

build.gradle

//Iterate over the contents of a tree tree.each {File file ->

println file

}

//Filter a tree

FileTree filtered = tree.matching { include 'org/gradle/api/**'

}

// Add trees together

FileTree sum = tree + fileTree(dir: 'src/test')

// Visit the elements of the tree tree.visit {element ->

println "$element.relativePath => $element.file"

}

Page 102 of 343