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 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.

Early versions of tar did not support path lengths greater than 100 characters. Modern versions of tar do so, but in incompatible ways. The behaviour of the tar task when it encounters such paths is controlled by 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. The tar task will then produce a GNU tar file which can have arbitrary length paths. Note however, that the resulting archive will only be able to be untarred with GNU tar. The default for the longfile attribute is warn which behaves just like the gnu option except that it produces a warning for each file path encountered that does not match the limit.

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

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 files (>100 chars) are to be handled. Allowable values are "truncate", "fail", "warn", "omit" and "gnu". Default is "warn".	No
includes	comma- or space-separated list of patterns of files that must be included. All files are included when omitted.	No
includesfile	the 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 files (except default excludes) are excluded when omitted.	No
excludesfile	the 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"). Default excludes are used when omitted.	No
compression	compression method. Allowable values are "none", "gzip" and "bzip2". Default is "none".	No

Nested Elements

The tar task supports nested tarfileset elements. These are extended Filesets which, in addition to the standard fileset elements, support three additional attributes

Attribute	Description	Required
mode	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. since Ant 1.6.	No
username	The username for the tar entry. This is not the same as the UID, which is not currently set by the tar task.	No
group	The groupname for the tar entry. This is not the same as the GID, which is not currently set by the tar task.	No
prefix	If the prefix attribute is set, all files in the fileset are prefixed with that path in the archive.	No
fullpath	If the fullpath attribute is set, the file in the fileset is written with that path in the archive. The prefix attribute, if specified, is ignored. It is an error to have more than one file specified in such a fileset.	No
preserveLeadingSlashes	Indicates whether leading `/'s should be preserved in the file names. Default is `false`.	No

Examples

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

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

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

tars 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="${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>

Writes 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 longfile="gnu"
     destfile="${dist.base}/${dist.name}-src.tar" >
  <tarfileset dir="${dist.name}/.." mode="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>

This example shows building a tar which uses the GNU extensions for long paths and where some files need to be marked as executable (mode 755) and the rest are 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.

Note: The tar task does not ensure that a file is only selected by one fileset. If the same file is selected by more than one fileset, 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}/...