Task

<zzpatch>

Adds, removes, renames and/or changes the contents of files and archives.

Implements the following features:

• Transforms regular files, directory trees, compressed files and entries in archive files, and also in nested archives
• Handles patch files in NORMAL, CONTEXT and UNIFIED diff format
• Replaces the contents of files from with that of an "update file"
• Does search-and-replace within files (SED like)
• Transform in-place as well as out-of-place
• Optionally keeps copies of the original files
• Adds, removes and renames files, directories and archive entries

To use this task, add this to your ANT build script:

<taskdef
    classpath="path/to/zz-patch-x.y.z-jar-with-dependencies.jar"
    resource="antlib.xml"
/>
 

Attribute Summary

Attributes

Name	Description
file="..."	Configures a file to be transformed; either in-place, or, iff tofile=... or todir=... is configured, out-of-place.
keepOriginals="..."	Whether to keep backup copies of files/entries that are modified or removed, renamed to ".
lookInto="..."	Look into compressed and archive contents if the format and the path match the given glob.
mode="..."	Configures how the files are processed.
todir="..."	Configures the directory for the output file created from file=... and/or the resource collection subelements.
tofile="..."	Configures the output file for the input file specified through file=....

Subelement Summary

Subelements

Name	Description
<add>	Configures that an entry be added to all archives that match the path pattern.
<patch>	Configures a transformation by applying a DIFF document.
<remove>	Configures that files/entries that match the name be deleted/removed.
<rename>	Configures that files/entries that match the name be renamed.
<substitute>	Configures that lines that match the regex="..." within files/entries that match the path="..." glob pattern be replaced with the replacement="..." string.
<update>	Configures that the contents of files/entries that match the name glob pattern be replaced with the contents of the given "update file".
Any Any resource collection	Adds another set of resources (<fileset>, <path>, ...) that will be patched.

Attribute Detail

Default values are underlined.

mode="TRANSFORM|CHECK|CHECK_AND_TRANSFORM"

Configures how the files are processed.

TRANSFORM

Execute the operation without previously checking if it actually changes any files.

CHECK

Execute the operation, but do not create or modify any files, and fail iff the operation does not produce an identical result. Since is typically much cheaper in this mode than in mode TRANSFORM, it may be efficient to execute in this mode first to check whether the transformation would modify and files, before executing it in TRANSFORM mode, particularly if you expect few or no modifications.

CHECK_AND_TRANSFORM

For in-place transformations: Before executing the actual transformation, verify that it will actually modify any files. Since checking whether a transformation would actually change any files is typically much cheaper than the executing the actual transformation, this mode may be more efficient than TRANSFORM mode, particularly if you expect few or no modifications.

keepOriginals="true|false"

Whether to keep backup copies of files/entries that are modified or removed, renamed to ".file-name.orig".

file="file"

Configures a file to be transformed; either in-place, or, iff tofile=... or todir=... is configured, out-of-place.

tofile="file"

Configures the output file for the input file specified through file=.... The default is to patch the input file in-place.

todir="existing-dir"

Configures the directory for the output file created from file=... and/or the resource collection subelements.

lookInto="format-glob:path-glob"

Look into compressed and archive contents if the format and the path match the given glob.

Supported archive formats are: [cpio, zip, dump, jar, tar, ar, arj, 7z].

Supported compression formats are: [snappy-raw, bzip2, gz, snappy-framed, pack200, xz, z, lzma].

The default is too look into any recognized archive or compressed contents.

Example:

lookInto="zip:**,tar:**,gz:**"

Subelement Detail

Any Any resource collection

Adds another set of resources (<fileset>, <path>, ...) that will be patched. Interface describing a collection of Resources.

<update>

Configures that the contents of files/entries that match the name glob pattern be replaced with the contents of the given "update file". A predicate that determines whether a path is applicable by matching it with a glob.

Attributes:

name="path"

Deprecated. Use path="..." instead

path="glob"

The glob to match the pathes against.

<substitute>

Configures that lines that match the regex="..." within files/entries that match the path="..." glob pattern be replaced with the replacement="..." string.

Alternatively, the regex and the replacement can be configured with <regex> and <replacement> subelements; one advantage of subelements is that they can contain <![CDATA[...]]> sections where you don't have to SGML-escape special characters.

You are not limited to line-wise pattern matching, but be careful with using greedy quantifiers, because these may require that the entire contents of each file needs to be loaded into memory.

Configures a substitution, i.e. the transformation of contents by finding pattern matches and replacing them with a replacement string.

Attributes:

inputEncoding="charset"

The encoding of the transformation input; defaults to the platform default encoding.

outputEncoding="charset"

The encoding of the transformation output; defaults to the platform default encoding.

regex="regex"

The regular expression the defines a match.

For the precise description of the supported regular-expression constructs, see here.

replacement="replacement"

The "replacement" that determines how each match is replaced.

For the precise description of the format, see here.

condition="expression"

Configures a condition that must evaluate to true before each occurrence is replaced.

The following variables are available in the expression:

path

The path currently being patched.

match

The text of the match.

occurrence

The index of the occurrence within the document, starting at zero.

name="path"

Deprecated. Use path="..." instead

path="glob"

The glob to match the pathes against.

Subelements:

<regex>

The regular expression the defines a match.

For the precise description of the supported regular-expression constructs, see here.

Text between start and end tag:

See ANT documentation.

<replacement>

The "replacement string" that determines how each match is replaced.

For the precise description of the format, see here.

Text between start and end tag:

See ANT documentation.

<patch>

Configures a transformation by applying a DIFF document.

A DIFF document generally contains differentials for one or more files. Each differential comprises a sequence of "hunks". Traditional format, context format and unified format are supported.

If the DIFF document describes more than on differential, then all but the first differential are ignored. The file name information in the differential is also ignored.

Configures a patch, i.e. the transformation of contents by applying a "DIFF document" to the input.

Attributes:

inputEncoding="value"

The encoding of the transformation input; defaults to the platform default encoding.

outputEncoding="value"

The encoding of the transformation output; defaults to the platform default encoding.

patchFile="patch-file"

The file that contains the DIFF document.

patchFileEncoding="charset"

The encoding of the patch file; defaults to the platform default encoding.

condition="expression"

Configures a condition that must evaluate to true before each DIFF hunk is applied.

The following variables are available in the expression:

path

The path currently being patched.

hunks

The hunks being applied.

hunkIndex

The index of the current hunk.

hunk

The current hunk.

lineNumber

The line number where the hunk starts.

name="path"

Deprecated. Use path="..." instead

path="glob"

The glob to match the pathes against.

<remove>

Configures that files/entries that match the name be deleted/removed. A predicate that determines whether a path is applicable by matching it with a glob.

Attributes:

name="path"

Deprecated. Use path="..." instead

path="glob"

The glob to match the pathes against.

<rename>

Configures that files/entries that match the name be renamed. A glob that implements renaming of a path.

Attributes:

name="path"

Deprecated. Use path="..." instead

path="glob"

The glob to match the pathes against.

<add>

Configures that an entry be added to all archives that match the path pattern. Configures an "add" operation, i.e. an entry that is added to an archive.

Attributes:

entryName="entry-name"

The name of the archive entry to add (may contain slashes).

contents="contents-file"

The file that contains the contents for the new archive entry.

name="path"

Deprecated. Use path="..." instead

path="glob"

The glob to match the pathes against.