## TarFileSet

`TarFileSet` has been a stand-alone type since Apache Ant 1.7.

A `<tarfileset>` 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 tarfileset is populated with tar entries found in the file src.
- When the dir attribute is used, the tarfileset is populated with filesystem files found under dir.

`<tarfileset>` supports all attributes of `<fileset>` in addition to those listed below. Note that tar archives in general don't contain entries with leading slashes so you shouldn't use include/exclude patterns that start with slashes either.

Since Ant 1.7, a tarfileset can be defined with the id attribute and referred to with the refid attribute.

### 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 tar 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. | No; default is 644
dirmode | A 3 digit octal string, specify the user, group and other modes in the standard Unix fashion. Only applies to directories. | No; default is 755
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
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. Since Ant 1.8.0 | No; defaults to true
encoding | The character encoding to use for filenames inside the zip file. For a list of possible values see the Supported Encodings. Since Ant 1.9.5 | No; defaults to default JVM character encoding

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.

Please note that currently only the tar task uses the permission and ownership attributes.

### Parameters specified as nested elements

#### any resource or single element resource collection

The specified resource will be used as src.

#### Examples

    <copy todir="some-dir">
     <tarfileset includes="lib/**">
       <bzip2resource>
         <url url="http://example.org/dist/some-archive.tar.bz2"/>
       </bzip2resource>
     </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.