## Archive FileSets

For each of the supported archiving formats there is a correspondig `fileset` resource collection.

Such a `fileset` is a special form of a `<fileset>` which can behave in 2 different ways :

- When the src attribute is used - or a nested resource collection has been specified, the fileset is populated with archive entries found in the file src.
- When the dir attribute is used, the fileset is populated with filesystem files found under dir.

Each archive fileset supports all attributes of `<fileset>` in addition to those listed below.

### Parameters

Attribute | Description | Required
prefix | all files in the fileset are prefixed with that path in the archive. | No
fullpath | the file described by the fileset is placed at that exact location in the archive. | No
src | may be used in place of the dir attribute to specify a file whose contents will be extracted and included in the archive. | No
filemode | A 3 digit octal string, specify the user, group and other modes in the standard Unix fashion. Only applies to plain files. Default is 644. | No
dirmode | A 3 digit octal string, specify the user, group and other modes in the standard Unix fashion. Only applies to directories. Default is 755. | No
erroronmissingarchive | Specify what happens if the archive does not exist. If true, a build error will happen; if false, the fileset will be ignored/empty. Defaults to true. | No
skipUnreadableEntries | Sometimes archives may contain entries that use features not (yet) supported by Apache Commons Compress, encryption for example. Trying to read from such an archive will normally lead to an error. Sometimes Commons Compress can signal it doesn't know how to handle an entry and if you set `skipUnreadableEntries` to true, the Compress Antlib will simply skip those entries, avoiding the error. since Compress Antlib 1.1 | No, defaults to false

The fullpath attribute can only be set for filesets that represent a single file. The prefix and fullpath attributes cannot both be set on the same fileset.

When using the src attribute, include and exclude patterns may be used to specify a subset of the archive for inclusion in the archive as with the dir attribute.

### Parameters specified as nested elements

#### any resource or single element resource collection

The specified resource will be used as src.

## ArFileSet

A `<arfileset>` is an archive fileset with attributes to specify user and group ids in addition to the parameters specified above.

### Parameters

Attribute | Description | Required
uid | The user identifier (UID) for the ar entry. This is an integer value and is not the same as the username. | No
gid | The group identifier (GID) for the ar entry. | No

#### Examples

>       <copy todir="some-dir">
>         <cmp:arfileset xmlns:cmp="antlib:org.apache.ant.compress">
>           <file file="some-archive.ar"/>
>         </cmp:arfileset>
>       </copy>

extracts some-archive.ar, uncompresses and extracts it on the fly and copies the contents of it into some-dir. File timestamps will be compared between the archive's entries and files inside the target directory, no files get overwritten unless they are out-of-date.

## ArjFileSet

Since Apache Compress Antlib 1.3.

A `<arjfileset>` is an archive fileset.

### Parameters

Attribute | Description | Required
encoding | The character encoding that has been used for filenames inside the arj file. For a list of possible values see http://java.sun.com/j2se/1.5.0/docs/guide/intl/encoding.doc.html. Defaults `native-encoding` which is the magic value for the platform's default character encoding. since Compress Antlib 1.3 | No

#### Examples

>       <copy todir="some-dir">
>         <cmp:arjfileset xmlns:cmp="antlib:org.apache.ant.compress">
>           <file file="some-archive.arj"/>
>         </cmp:arjfileset>
>       </copy>

extracts some-archive.arj and copies the contents of it into some-dir. File timestamps will be compared between the archive's entries and files inside the target directory, no files get overwritten unless they are out-of-date.

## CpioFileSet

A `<cpiofileset>` is an archive fileset with attributes to specify user and group ids in addition to the parameters specified above.

### Parameters

Attribute | Description | Required
uid | The user identifier (UID) for the cpio entry. This is an integer value and is not the same as the username. | No
gid | The group identifier (GID) for the cpio entry. | No
encoding | The character encoding that has been used for filenames inside the cpio file. For a list of possible values see http://java.sun.com/j2se/1.5.0/docs/guide/intl/encoding.doc.html. Defaults `native-encoding` which is the magic value for the platform's default character encoding. since Compress Antlib 1.3 | No

#### Examples

>       <copy todir="some-dir">
>         <cmp:cpiofileset xmlns:cmp="antlib:org.apache.ant.compress">
>           <file file="some-archive.cpio"/>
>         </cmp:cpiofileset>
>       </copy>

extracts some-archive.cpio, uncompresses and extracts it on the fly and copies the contents of it into some-dir. File timestamps will be compared between the archive's entries and files inside the target directory, no files get overwritten unless they are out-of-date.

## DumpFileSet

Since Apache Compress Antlib 1.1.

A `<dumpfileset>` is an archive fileset with attributes to specify user and group ids in addition to the parameters specified above.

### Parameters

Attribute | Description | Required
uid | The user identifier (UID) for the dump entry. This is an integer value and is not the same as the username. | No
gid | The group identifier (GID) for the dump entry. | No
encoding | The character encoding that has been used for filenames inside the dump file. For a list of possible values see http://java.sun.com/j2se/1.5.0/docs/guide/intl/encoding.doc.html. Defaults `native-encoding` which is the magic value for the platform's default character encoding. since Compress Antlib 1.3 | No

#### Examples

>       <copy todir="some-dir">
>         <cmp:dumpfileset xmlns:cmp="antlib:org.apache.ant.compress">
>           <file file="some-archive.dump"/>
>         </cmp:dumpfileset>
>       </copy>

extracts some-archive.dump, uncompresses and extracts it on the fly and copies the contents of it into some-dir. File timestamps will be compared between the archive's entries and files inside the target directory, no files get overwritten unless they are out-of-date.

## SevenZFileSet

Since Apache Compress Antlib 1.3.

A `<sevenzfileset>` is an archive fileset for 7z archives.

## TarFileSet

A `<tarfileset>` is an archive fileset with attributes to specify user and group ownership in addition to the parameters specified above.

### Parameters

Attribute | Description | Required
username | The username for the tar entry. This is not the same as the UID. | No
group | The groupname for the tar entry. This is not the same as the GID. | No
uid | The user identifier (UID) for the tar entry. This is an integer value and is not the same as the username. | No
gid | The group identifier (GID) for the tar entry. | No
encoding | The character encoding that has been used for filenames inside the tar file. For a list of possible values see http://java.sun.com/j2se/1.5.0/docs/guide/intl/encoding.doc.html. Defaults `native-encoding` which is the magic value for the platform's default character encoding. since Compress Antlib 1.2 | No

#### Examples

>       <copy todir="some-dir">
>         <cmp:tarfileset xmlns:cmp="antlib:org.apache.ant.compress"
>             includes="lib/**">
>           <cmp:bzip2resource>
>             <url url="http://example.org/dist/some-archive.tar.bz2"/>
>           </cmp:bzip2resource>
>         </cmp:tarfileset>
>       </copy>

downloads the archive some-archive.tar.bz2, uncompresses and extracts it on the fly, copies the contents of the lib directory into some-dir and discards the rest of the archive. File timestamps will be compared between the archive's entries and files inside the target directory, no files get overwritten unless they are out-of-date.

## ZipFileSet

A `<zipfileset>` is an archive fileset with an attribute to specify the encoding of filenames inside the archive in addition to the parameters specified above.

### Parameters

Attribute | Description | Required
encoding | The character encoding to use for filenames inside the zip file. For a list of possible values see http://java.sun.com/j2se/1.5.0/docs/guide/intl/encoding.doc.html. Defaults to the platform's default character encoding. | No

#### Examples

      <cmp:zip destfile="${dist}/manual.zip" xmlns:cmp="antlib:org.apache.ant.compress">
        <cmp:zipfileset dir="htdocs/manual" prefix="docs/user-guide"/>
        <cmp:zipfileset dir="." includes="ChangeLog27.txt" fullpath="docs/ChangeLog.txt"/>
        <cmp:zipfileset src="examples.zip" includes="**/*.html" prefix="docs/examples"/>
      </cmp:zip>

zips all files in the `htdocs/manual` directory into the `docs/user-guide` directory in the archive, adds the file `ChangeLog27.txt` in the current directory as `docs/ChangeLog.txt`, and includes all the html files in `examples.zip` under `docs/examples`. The archive might end up containing the files:

> `docs/user-guide/html/index.html
> docs/ChangeLog.txt
> docs/examples/index.html
> `