The file plugin provides a number of methods that help you deal with files and archives. The features of the plugin are also the public methods of the plugin class so you can refer to the Groovy Doc for more information.

LATEST VERSION: 1.0.0

Loading the Plugin

Here is how you load this plugin:

file = loadPlugin(id: "org.savantbuild.plugin:file:1.0.0")

FileSets

Most of the methods on the file plugin use FileSets to identify files. The fileSet and optionalFileSet methods allow you to specify files that are either required or optional. If a required FileSet references a dir that doesn’t exist, an exception will be thrown.

You can also reduce a FileSet by supplying it with a list of patterns to include or exclude. These patterns are Regular Expressions (NOT Ant style expressions). These are specified via the includePatterns and excludePatterns parameters.

Here are the attributes you can supply to FileSets:

ArchiveFileSet

The tar and zip methods allow you to supply specialized FileSets in order to provide more information about how files and directories are stored inside TAR and ZIP files. Here are the attributes you can supply to the ArchiveFileSet:

Filter Definitions

Some methods on this plugin also take Filter definitions. A filter consists of a token and a value. The token is replaced with the value for operations like rename or filtering while copying.

Here are the attribute you can supply to Filter definitions:

Appending to a File

The append method allows you to append the contents of files to another file. It takes 1 or more FileSets inside its closure. It also takes these parameters:

Here is an example of calling this method:

file.append(to: "some-file.txt") {
  fileSet(dir: "src/main/text-files", includePatterns: [~/.+.txt/])
}

Copying Files

The copy method on the file plugin allows you to copy files between directories. This method takes 1 or more FileSets inside its closure. It also takes these parameters:

• to - (required) The location to copy the files to. Must be an existing directory or not exist. If the location doesn’t exist, it is created.

Here is an example of using this method:

file.copy(to: "build/distributions/bin") {
  fleSet(dir: "src/main/scripts")
}

This copies all of the files (recursively) from the src/main/scripts directory to the build/distributions/bin directory.

Here’s an example that only copies a specific set of files.

file.copy(to: "build/distributions/bin") {
  fleSet(dir: "src/main/scripts", includePatterns: [/.*\.sh/])
}

This copies all of the files (recursively) from the src/main/scripts directory with an extension of .sh to the build/distributions/bin directory.

You can also filter text inside files while copying. To do this, you supply 1 or more filter definitions inside the closure. Here is an example of using filters:

file.copy(to: "build/distributions/bin") {
  fleSet(dir: "src/main/scripts", includePatterns: [/.*\.sh/])
  filter(token: "%VERSION%", value: "${project.version}")
}

Copy a Single File

The copyFile allows you to copy a single file to another location. It takes these parameters:

Here is an example of calling this method:

file.copyFile(file: "some-file.txt", to: "build/some-file-renamed.txt")

Deleting Files

The delete method allows you to delete 0 or more files. It takes 1 or more FileSets inside its closure. Here is an example of calling this method:

file.delete {
  fileSet(dir: "build/example", includePatterns: [~/foobar.+/])
}

Jarring Files

The jar method on the file plugin allows you to create Jar files. It takes 1 or more FileSets inside its closure. It also takes these parameters:

Here is an example of using this method:

file.jar(file: "build/jars/foobar.jar") {
  fileSet(dir: "src/main/java")
  optionalFileSet(dir: "build/output")
}

This add all of the files in the src/main/java directory to the jar file build/jars/foobar.jar. It also optionally adds all of the files from the build/output directory to the jar file if that directory exists.

Making a Directory

The mkdir allows you to create a directory. It takes these parameters:

Here is an example of calling this method:

file.mkdir(dir: "build/test")

Pruning

The prune method on the file plugin allows you to delete a directory and everything inside it. It takes these parameters:

Here is an example of using this method:

file.prune(dir: "build/classes/main")

NOTE: This method correctly handles symlinks by removing the link. This DOES NOT traverse symlinks.

Renaming Files

The rename method allows you to rename multiple files at the same time. This takes 1 or more FileSets inside its closure. It renames based on 1 or more Filter definitions that are also provided inside the closure. Here is an example of calling this method:

file.rename {
  fileSet(dir: "build/classes/main")
  filter(token: "foobar", value: "baz")
}

Creating Symlinks

The symlink method allows you to create symlinks. You almost never need to unlink a symlink because Savant almost never traverses symlinks. This method takes these parameters:

Here is an example of calling this method:

file.symlink(target: "build/classes/main", link: "/tmp/foo/bar")

Tarring Files

The tar method on the file plugin allows you to create Tarballs. This method takes these parameters:

Here is an example of using this method:

file.tar(file: "build/tars/foobar.tar.gz", compress: true) {
  fileSet(dir: "src/main/java")
}

This adds all of the files in the src/main/java directory to the tarball build/tars/foobar.tar.gz. This also compresses the tarball.

You can also supply ArchiveFileSets to the tar method. These are called tarFileSets. Here is an example of using tarFileSets:

file.tar(file: "build/tars/foobar.tar.gz", compress: true) {
  tarFileSet(dir: "src/main/java", prefix: "/usr/local/foobar", mode: 0x744, userName: "root", groupName: "root")
}

Unjar Files

The unjar method allows you to extract a JAR file. This method takes these parameters:

Here is an example of calling this method;

file.unjar(file: "build/jars/foobar.jar", to: "build/output")

Untar Files

The untar method allows you to extract a TAR file. This method takes these parameters:

Here is an example of calling this method;

file.untar(file: "build/tars/foobar.tar.gz", to: "build/output")

Unzip Files

The unzip method allows you to extract a ZIP file. This method takes these parameters:

Here is an example of calling this method;

file.unzip(file: "build/zips/foobar.zip", to: "build/output")

Zipping Files

The zip method on the file plugin allows you to create ZIP files. The files in the ZIP retain the mode of the original file, but not the owner and group. This method takes these parameters:

Here is an example of using this method:

file.tar(file: "build/zips/foobar.zip") {
  fileSet(dir: "src/main/java")
}

This adds all of the files in the src/main/java directory to the ZIP build/tars/foobar.zip.

You can also supply ArchiveFileSets to the zip method. These are called zipFileSets. Here is an example of using zipFileSets:

file.zip(file: "build/zips/foobar.zip") {
  zipFileSet(dir: "src/main/java", prefix: "/usr/local/foobar", mode: 0x744)
}

The userName and groupName attributes for ArchiveFileSets are allowed here but the ZIP method does not support them yet. The JDK implementation for ZIP files does support them, but lacks support for Unix mode. Likewise, the Ant ZIP implementation supports Unix file mode, but lacks support for ownership. We opted to use the Ant implementation until we can afford the time to write our own that supports everything in modern ZIP files.