trunk/proposal/xdocs/src/org/apache/tools/ant/taskdefs/Tar.xml

<!-- tar task -->
<external>
<description>
<p>Creates a tar archive.</p>

<p>The <i>basedir</i> attribute is the reference directory from where to tar.</p>

<p>This task is a <a href="../dirtasks.html#directorybasedtasks">directory based task</a>
and, as such, forms an implicit <a href="../CoreTypes/fileset.html">Fileset</a>. This
defines which files, relative to the <i>basedir</i>, 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.</p>

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

<p>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 <i>longfile</i> attribute.
If the longfile attribute is set to <code>fail</code>, any long paths will
cause the tar task to fail.  If the longfile attribute is set to
<code>truncate</code>, 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 <code>omit</code> 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 <code>gnu</code>. 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 <code>warn</code> which behaves just like the gnu option except
that it produces a warning for each file path encountered that does not match
the limit.</p>

<p>Note that this task does not perform compression. You might want to use the
<a href="gzip.html">GZip</a> task to prepare a .tar.gz package.</p>
</description>

<section anchor="examples" name="Examples">
<pre>  &lt;tar tarfile=&quot;${dist}/manual.tar&quot; basedir=&quot;htdocs/manual&quot;/&gt;
  &lt;gzip zipfile=&quot;${dist}/manual.tar.gz&quot; src=&quot;${dist}/manual.tar&quot;/&gt;</pre>
<p>tars all files in the <code>htdocs/manual</code> directory into a file called <code>manual.tar</code>
in the <code>${dist}</code>  directory, then applies the gzip task to compress
it.</p>
<pre>  &lt;tar destfile=&quot;${dist}/manual.tar&quot;
       basedir=&quot;htdocs/manual&quot;
       excludes=&quot;mydocs/**, **/todo.html&quot;
  /&gt;</pre>
<p>tars all files in the <code>htdocs/manual</code> directory into a file called <code>manual.tar</code>
in the <code>${dist}</code> directory. Files in the directory <code>mydocs</code>,
or files with the name <code>todo.html</code> are excluded.</p>

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

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


<pre>&lt;tar longfile=&quot;gnu&quot;
     destfile=&quot;${dist.base}/${dist.name}-src.tar&quot; &gt;
  &lt;tarfileset dir=&quot;${dist.name}/..&quot; mode=&quot;755&quot; username=&quot;ant&quot; group=&quot;ant&quot;&gt;
    &lt;include name=&quot;${dist.name}/bootstrap.sh&quot;/&gt;
    &lt;include name=&quot;${dist.name}/build.sh&quot;/&gt;
  &lt;/tarfileset&gt;
  &lt;tarfileset dir=&quot;${dist.name}/..&quot; username=&quot;ant&quot; group=&quot;ant&quot;&gt;
    &lt;include name=&quot;${dist.name}/**&quot;/&gt;
    &lt;exclude name=&quot;${dist.name}/bootstrap.sh&quot;/&gt;
    &lt;exclude name=&quot;${dist.name}/build.sh&quot;/&gt;
  &lt;/tarfileset&gt;
&lt;/tar&gt; </pre>

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

<p><strong>Note: </strong> 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.</p>

<p><strong>Note:</strong> 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,
<code>${dist.name}</code> is not an absolute path, but a simple name
of a directory, so <code>${dist.name}</code> is a valid path relative
to <code>${dist.name}/..</code>.</p>

</section>
</external>