2006-09-11 04:19:00 +00:00
|
|
|
<!--
|
|
|
|
|
Licensed to the Apache Software Foundation (ASF) under one or more
|
|
|
|
|
contributor license agreements. See the NOTICE file distributed with
|
|
|
|
|
this work for additional information regarding copyright ownership.
|
|
|
|
|
The ASF licenses this file to You under the Apache License, Version 2.0
|
|
|
|
|
(the "License"); you may not use this file except in compliance with
|
|
|
|
|
the License. You may obtain a copy of the License at
|
|
|
|
|
|
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
|
|
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
|
|
|
distributed under the License is distributed on an "AS IS" BASIS,
|
|
|
|
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
|
|
|
See the License for the specific language governing permissions and
|
|
|
|
|
limitations under the License.
|
|
|
|
|
-->
|
2001-02-13 12:32:01 +00:00
|
|
|
<html>
|
|
|
|
|
|
|
|
|
|
<head>
|
|
|
|
|
<meta http-equiv="Content-Language" content="en-us">
|
2005-04-29 18:58:16 +00:00
|
|
|
<link rel="stylesheet" type="text/css" href="../stylesheets/style.css">
|
2002-02-03 22:00:42 +00:00
|
|
|
<title>Tar Task</title>
|
2001-02-13 12:32:01 +00:00
|
|
|
</head>
|
|
|
|
|
|
|
|
|
|
<body>
|
|
|
|
|
|
2018-01-22 23:52:21 +01:00
|
|
|
<h2 id="tar">Tar</h2>
|
2001-02-13 12:32:01 +00:00
|
|
|
<h3>Description</h3>
|
|
|
|
|
<p>Creates a tar archive.</p>
|
2018-02-28 07:58:59 +01:00
|
|
|
<p>The <var>basedir</var> 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="../Types/fileset.html">Fileset</a>. This defines which files,
|
|
|
|
|
relative to the <var>basedir</var>, will be included in the archive. The <code>tar</code> 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 <code>tar</code> 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.</p>
|
|
|
|
|
|
|
|
|
|
<p>Early versions of <code>tar</code> 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 <code>pax</code> utility first introduced them) that
|
|
|
|
|
among another things addressed file names longer than 100 characters. All modern implementations of
|
|
|
|
|
tar support PAX extension headers.</p>
|
|
|
|
|
|
|
|
|
|
<p>Ant's tar support predates the standard with PAX extension headers, it supports different
|
|
|
|
|
dialects that can be enabled using the <var>longfile</var> attribute. If the <var>longfile</var>
|
|
|
|
|
attribute is set to <q>fail</q>, any long paths will cause the tar task to fail. If
|
|
|
|
|
the <var>longfile</var> attribute is set to <q>truncate</q>, any long paths will be truncated to the
|
|
|
|
|
100 character maximum length prior to adding to the archive. If the value of the <var>longfile</var>
|
|
|
|
|
attribute is set to <q>omit</q> 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.</p>
|
|
|
|
|
|
|
|
|
|
<p>If the loss of path or file information is not acceptable, and it rarely is, <var>longfile</var>
|
|
|
|
|
may be set to the value <q>gnu</q> or <q>posix</q>. With <q>posix</q> Ant will add PAX extension
|
|
|
|
|
headers, with <q>gnu</q> it adds GNU tar specific extensions that newer versions of GNU tar
|
|
|
|
|
call <q>oldgnu</q>. 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.</p>
|
|
|
|
|
|
|
|
|
|
<p>The default for the <var>longfile</var> attribute is <q>warn</q> which behaves just like
|
|
|
|
|
the <q>gnu</q> option except that it produces a warning for each filepath encountered that does not
|
|
|
|
|
match the limit. It uses <q>gnu</q> rather than <q>posix</q> for backwards compatibility
|
|
|
|
|
reasons.</p>
|
|
|
|
|
|
|
|
|
|
<p>To achieve best interoperability you should use either <q>fail</q> or <q>posix</q> for
|
|
|
|
|
the <var>longfile</var> attribute.</p>
|
|
|
|
|
|
|
|
|
|
<p>This task can perform compression by setting the <var>compression</var> attribute
|
|
|
|
|
to <q>gzip</q>, <q>bzip2</q>, or <q>xz</q>.</p>
|
2001-02-13 12:32:01 +00:00
|
|
|
|
|
|
|
|
<h3>Parameters</h3>
|
2018-02-28 07:58:59 +01:00
|
|
|
<table class="attr">
|
2001-02-13 12:32:01 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<th>Attribute</th>
|
|
|
|
|
<th>Description</th>
|
|
|
|
|
<th>Required</th>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>destfile</td>
|
|
|
|
|
<td>the tar file to create.</td>
|
|
|
|
|
<td>Yes</td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>basedir</td>
|
|
|
|
|
<td>the directory from which to tar the files.</td>
|
|
|
|
|
<td>No</td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>longfile</td>
|
|
|
|
|
<td>Determines how long filenames (> 100 chars) are to be handled. Allowed values
|
|
|
|
|
are <q>truncate</q>, <q>fail</q>, <q>warn</q>, <q>omit</q>, <q>gnu</q> and <q>posix</q>.</td>
|
|
|
|
|
<td>No; default is <q>warn</q></td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>includes</td>
|
|
|
|
|
<td>comma- or space-separated list of patterns of files that must be included.</td>
|
|
|
|
|
<td>No; defaults to all (<q>**</q>)</td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>includesfile</td>
|
|
|
|
|
<td>name of a file. Each line of this file is taken to be an include pattern</td>
|
|
|
|
|
<td>No</td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>excludes</td>
|
|
|
|
|
<td>comma- or space-separated list of patterns of files that must be excluded.</td>
|
|
|
|
|
<td>No; defaults to default excludes or none if <var>defaultexcludes</var> is <q>no</q></td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>excludesfile</td>
|
|
|
|
|
<td>name of a file. Each line of this file is taken to be an exclude pattern</td>
|
|
|
|
|
<td>No</td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>defaultexcludes</td>
|
|
|
|
|
<td>indicates whether default excludes should be used or not (<q>yes|no</q>).</td>
|
|
|
|
|
<td>No; defaults to <q>yes</q></td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
2002-04-24 03:09:06 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>compression</td>
|
|
|
|
|
<td>compression method. Allowable values are <q>none</q>, <q>gzip</q>, <q>xz</q>
|
|
|
|
|
and <q>bzip2</q>.</td>
|
|
|
|
|
<td>No; default is <q>warn</q></td>
|
2002-04-24 03:09:06 +00:00
|
|
|
</tr>
|
2015-04-21 21:36:07 +02:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>encoding</td>
|
|
|
|
|
<td>The character encoding to use for filenames inside the tar file. For a list of possible
|
|
|
|
|
values see
|
|
|
|
|
the <a href="https://docs.oracle.com/javase/8/docs/technotes/guides/intl/encoding.doc.html">Supported
|
|
|
|
|
Encodings</a>.<br/><em>Since Ant 1.9.5</em>
|
|
|
|
|
<td>No; defaults to default JVM character encoding</td>
|
2015-04-21 21:36:07 +02:00
|
|
|
</tr>
|
2001-02-13 12:32:01 +00:00
|
|
|
</table>
|
|
|
|
|
|
2018-03-05 17:35:30 +01:00
|
|
|
<h3>Parameters specified as nested elements</h3>
|
2005-10-19 18:40:56 +00:00
|
|
|
|
2018-03-05 17:35:30 +01:00
|
|
|
<p>The task supports nested <a href="../Types/tarfileset.html">tarfileset</a> elements. These
|
2018-02-28 07:58:59 +01:00
|
|
|
are extended <a href="../Types/fileset.html">FileSets</a> which, in addition to the standard
|
|
|
|
|
elements, support one additional attributes</p>
|
2001-02-13 12:32:01 +00:00
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<table class="attr">
|
2001-02-13 12:32:01 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<th>Attribute</th>
|
|
|
|
|
<th>Description</th>
|
|
|
|
|
<th>Required</th>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
2002-02-04 21:50:42 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>preserveLeadingSlashes</td>
|
|
|
|
|
<td>Indicates whether leading <q>/</q> should be preserved in the file names.</td>
|
|
|
|
|
<td>No; default is <q>false</q></td>
|
2002-02-04 21:50:42 +00:00
|
|
|
</tr>
|
2001-02-13 12:32:01 +00:00
|
|
|
</table>
|
|
|
|
|
|
2005-10-19 18:40:56 +00:00
|
|
|
<h4>any other resource collection</h4>
|
2018-03-05 17:35:30 +01:00
|
|
|
<p><a href="../Types/resources.html#collection">resource collections</a> are used to select groups
|
2018-02-28 07:58:59 +01:00
|
|
|
of files to archive.</p>
|
|
|
|
|
<p>Prior to Apache Ant 1.7 only <code><fileset></code> has been supported as a nested
|
|
|
|
|
element.</p>
|
2005-10-19 18:40:56 +00:00
|
|
|
|
2001-02-13 12:32:01 +00:00
|
|
|
<h3>Examples</h3>
|
2005-03-10 13:01:55 +00:00
|
|
|
<pre>
|
2007-12-18 08:41:04 +00:00
|
|
|
<tar destfile="${dist}/manual.tar" basedir="htdocs/manual"/>
|
|
|
|
|
<gzip destfile="${dist}/manual.tar.gz" src="${dist}/manual.tar"/></pre>
|
2018-02-28 07:58:59 +01:00
|
|
|
|
|
|
|
|
<p>tars all files in the <samp>htdocs/manual</samp> directory into a file
|
|
|
|
|
called <samp>manual.tar</samp> in the <samp>${dist}</samp> directory, then applies
|
|
|
|
|
the <code>gzip</code> task to compress it.</p>
|
2007-12-18 08:41:04 +00:00
|
|
|
|
2005-03-10 13:01:55 +00:00
|
|
|
<pre>
|
|
|
|
|
<tar destfile="${dist}/manual.tar"
|
2007-12-18 08:41:04 +00:00
|
|
|
basedir="htdocs/manual"
|
2018-01-22 23:52:21 +01:00
|
|
|
excludes="mydocs/**, **/todo.html"/></pre>
|
2018-02-28 07:58:59 +01:00
|
|
|
|
|
|
|
|
<p>tars all files in the <samp>htdocs/manual</samp> directory into a file
|
|
|
|
|
called <samp>manual.tar</samp> in the <samp>${dist}</samp> directory. Files in the
|
|
|
|
|
directory <samp>mydocs</samp>, or files with the name <samp>todo.html</samp> are excluded.</p>
|
2001-02-13 12:32:01 +00:00
|
|
|
|
2002-02-04 21:50:42 +00:00
|
|
|
<pre>
|
|
|
|
|
<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></pre>
|
2018-02-28 07:58:59 +01:00
|
|
|
|
|
|
|
|
<p>Writes the file <samp>docs/readme.txt</samp> as <samp>/usr/doc/ant/README</samp> into the
|
|
|
|
|
archive. All <samp>*.html</samp> files in the <samp>docs</samp> directory are prefixed
|
|
|
|
|
by <samp>/usr/doc/ant</samp>, so for example <samp>docs/index.html</samp> is written
|
|
|
|
|
as <samp>/usr/doc/ant/index.html</samp> to the archive.</p>
|
2002-02-04 21:50:42 +00:00
|
|
|
|
2005-03-10 13:01:55 +00:00
|
|
|
<pre>
|
|
|
|
|
<tar longfile="gnu"
|
2007-12-18 08:41:04 +00:00
|
|
|
destfile="${dist.base}/${dist.name}-src.tar">
|
2009-07-21 04:15:44 +00:00
|
|
|
<tarfileset dir="${dist.name}/.." filemode="755" username="ant" group="ant">
|
2001-02-13 12:32:01 +00:00
|
|
|
<include name="${dist.name}/bootstrap.sh"/>
|
|
|
|
|
<include name="${dist.name}/build.sh"/>
|
2002-02-03 22:23:37 +00:00
|
|
|
</tarfileset>
|
|
|
|
|
<tarfileset dir="${dist.name}/.." username="ant" group="ant">
|
2001-02-13 12:32:01 +00:00
|
|
|
<include name="${dist.name}/**"/>
|
|
|
|
|
<exclude name="${dist.name}/bootstrap.sh"/>
|
|
|
|
|
<exclude name="${dist.name}/build.sh"/>
|
2001-03-22 08:06:21 +00:00
|
|
|
</tarfileset>
|
2018-02-28 07:58:59 +01:00
|
|
|
</tar></pre>
|
2001-02-13 12:32:01 +00:00
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<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>
|
2001-02-13 12:32:01 +00:00
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<p><strong>Note</strong>: The <code>tar</code> 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.</p>
|
2001-08-07 05:58:12 +00:00
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<p><strong>Note</strong>: The patterns in the <code>include</code> and <code>exclude</code> elements
|
|
|
|
|
are considered to be relative to the corresponding <var>dir</var> attribute as with all other
|
|
|
|
|
filesets. In the example above, <samp>${dist.name}</samp> is not an absolute path, but a simple
|
|
|
|
|
name of a directory, so <samp>${dist.name}</samp> is a valid path relative
|
|
|
|
|
to <samp>${dist.name}/..</samp>.</p>
|
2007-12-18 08:41:04 +00:00
|
|
|
|
2005-10-19 18:40:56 +00:00
|
|
|
<pre>
|
2007-12-18 08:41:04 +00:00
|
|
|
<tar destfile="release.tar.gz" compression="gzip">
|
2005-10-19 18:40:56 +00:00
|
|
|
<zipfileset src="release.zip"/>
|
2018-02-28 07:58:59 +01:00
|
|
|
</tar></pre>
|
2005-10-19 18:40:56 +00:00
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<p>Re-packages 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.</p>
|
2007-12-18 08:41:04 +00:00
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<p><strong>Note</strong>: Please note the <code>tar</code> 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.</p>
|
2001-02-13 12:32:01 +00:00
|
|
|
|
|
|
|
|
</body>
|
|
|
|
|
</html>
|
