Tar Task

## Tar

### Description

Creates a tar archive.

The basedir attribute is the reference directory from where to tar.

This task is a directory based task and, as such, forms an implicit Fileset. This defines which files, relative to the basedir, will be included in the archive. The `tar` task supports all the attributes of Fileset to refine the set of files to be included in the implicit fileset.

In addition to the implicit fileset, the `tar` task supports nested resource collections and a special form of filesets. These filesets are extended to allow control over the access mode, username and groupname to be applied to the tar entries. This is useful, for example, when preparing archives for Unix systems where some files need to have execute permission. By default this task will use Unix permissions of 644 for files and 755 for directories.

Early versions of `tar` utility did not support paths longer than 100 characters. Over time several incompatible extensions have been developed until a new POSIX standard was created that added so called PAX extension headers (as the `pax` utility first introduced them) that among another things addressed file names longer than 100 characters. All modern implementations of `tar` support PAX extension headers.

Ant's `tar` support predates the standard with PAX extension headers, it supports different dialects that can be enabled using the longfile attribute. If the longfile attribute is set to fail, any long paths will cause the `tar` task to fail. If the longfile attribute is set to truncate, any long paths will be truncated to the 100 character maximum length prior to adding to the archive. If the value of the longfile attribute is set to omit then files containing long paths will be omitted from the archive. Either option ensures that the archive can be untarred by any compliant version of `tar`.

If the loss of path or file information is not acceptable, and it rarely is, longfile may be set to the value gnu or posix. With posix Ant will add PAX extension headers, with gnu it adds GNU `tar` specific extensions that newer versions of GNU `tar` call oldgnu. GNU `tar` still creates these extensions by default but supports PAX extension headers as well. Either choice will produce a tar file which can have arbitrary length paths. Note however, that the resulting archive will only be able to be untarred with `tar` tools that support the chosen format.

The default for the longfile attribute is warn which behaves just like the gnu option except that it produces a warning for each filepath encountered that does not match the limit. It uses gnu rather than posix for backwards compatibility reasons.

To achieve best interoperability you should use either fail or posix for the longfile attribute.

This task can perform compression by setting the compression attribute to gzip, bzip2, or xz.

### Parameters

Attribute | Description | Required
--- | --- | ---
destfile | the tar file to create. | Yes
basedir | the directory from which to tar the files. | No
longfile | Determines how long filenames (> 100 chars) are to be handled. Allowed values are truncate, fail, warn, omit, gnu and posix. | No; default is warn
includes | comma- or space-separated list of patterns of files that must be included. | No; defaults to all (**)
includesfile | name of a file. Each line of this file is taken to be an include pattern | No
excludes | comma- or space-separated list of patterns of files that must be excluded. | No; defaults to default excludes or none if defaultexcludes is no
excludesfile | name of a file. Each line of this file is taken to be an exclude pattern | No
defaultexcludes | indicates whether default excludes should be used or not (yes|no). | No; defaults to yes
compression | compression method. Allowable values are none, gzip, xz and bzip2. | No; default is none
encoding | The character encoding to use for filenames inside the tar file. For a list of possible values see the Supported Encodings. In general the tar format expects names to use a single byte encoding and specifying a multi-byte encoding here may lead to archives that cannot be properly extracted by my tar tools. Since Ant 1.9.5 | No; defaults to default JVM character encoding

### Parameters specified as nested elements

The task supports nested tarfileset elements. These are extended FileSets which, in addition to the standard elements, support one additional attributes

Attribute | Description | Required
--- | --- | ---
preserveLeadingSlashes | Indicates whether leading / should be preserved in the file names. | No; default is false

#### any other resource collection

resource collections are used to select groups of files to archive.

Prior to Apache Ant 1.7 only `<fileset>` has been supported as a nested element.

### Examples

Tar all files in the `htdocs/manual` directory into a file called `manual.tar` in the `${dist}` directory, then apply the `gzip` task to compress it.

    <tar destfile="${dist}/manual.tar" basedir="htdocs/manual"/>
    <gzip destfile="${dist}/manual.tar.gz" src="${dist}/manual.tar"/>

Tar all files in the `htdocs/manual` directory into a file called `manual.tar` in the `${dist}` directory. Files in the directory `mydocs`, or files with the name `todo.html` are excluded.

    <tar destfile="${dist}/manual.tar"
         basedir="htdocs/manual"
         excludes="mydocs/**, **/todo.html"/>

Write the file `docs/readme.txt` as `/usr/doc/ant/README` into the archive. All `*.html` files in the `docs` directory are prefixed by `/usr/doc/ant`, so for example `docs/index.html` is written as `/usr/doc/ant/index.html` to the archive.

    <tar destfile="${basedir}/docs.tar">
      <tarfileset dir="${dir.src}/docs"
                  fullpath="/usr/doc/ant/README"
                  preserveLeadingSlashes="true">
        <include name="readme.txt"/>
      </tarfileset>
      <tarfileset dir="${dir.src}/docs"
                  prefix="/usr/doc/ant"
                  preserveLeadingSlashes="true">
        <include name="*.html"/>
      </tarfileset>
    </tar>

Build a tar which uses the GNU extensions for long paths where some files need to be marked as executable (mode 755) and the rest use the default mode (read-write by owner). The first fileset selects just the executable files. The second fileset must exclude the executable files and include all others.

    <tar longfile="gnu"
         destfile="${dist.base}/${dist.name}-src.tar">
      <tarfileset dir="${dist.name}/.." filemode="755" username="ant" group="ant">
        <include name="${dist.name}/bootstrap.sh"/>
        <include name="${dist.name}/build.sh"/>
      </tarfileset>
      <tarfileset dir="${dist.name}/.." username="ant" group="ant">
        <include name="${dist.name}/**"/>
        <exclude name="${dist.name}/bootstrap.sh"/>
        <exclude name="${dist.name}/build.sh"/>
      </tarfileset>
    </tar>

Note: The `tar` task does not ensure that a file is only selected by one resource collection. If the same file is selected by more than one collection, it will be included in the tar file twice, with the same path.

Note: The patterns in the `include` and `exclude` elements are considered to be relative to the corresponding dir attribute as with all other filesets. In the example above, `${dist.name}` is not an absolute path, but a simple name of a directory, so `${dist.name}` is a valid path relative to `${dist.name}/..`.

Re-package a ZIP archive as a GZip compressed tar archive. If Unix file permissions have been stored as part of the ZIP file, they will be retained in the resulting tar archive.

    <tar destfile="release.tar.gz" compression="gzip">
      <zipfileset src="release.zip"/>
    </tar>

Note: Please note the `tar` task creates a tar file, it does not append to an existing tar file. The existing tar file is replaced instead. As with most tasks in Ant, the task only takes action if the output file (the tar file in this case) is older than the input files, or if the output file does not exist.