1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
|
<!--
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.
-->
<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<link rel="stylesheet" type="text/css" href="../stylesheets/style.css">
<title>Tar Task</title>
</head>
<body>
<h2><a name="tar">Tar</a></h2>
<h3>Description</h3>
<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="../Types/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
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 tar did not support path lengths greater 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.</p>
<p>Ant's tar support predates the standard with PAX extension headers,
it supports different dialects that can be enabled using 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.</p>
<p>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> or <code>posix</code>. With <code>posix</code>
Ant will add PAX extension headers, with <code>gnu</code> 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.
<p>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. It uses gnu rather than posix for backwards compatibility
reasons.</p>
<p>To achivieve best interoperability you should use
either <code>fail</code> or <code>posix</code> for the longfile attribute.</p>
<p>This task can perform compression by setting the compression attribute to "gzip"
or "bzip2".</p>
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td valign="top"><b>Attribute</b></td>
<td valign="top"><b>Description</b></td>
<td valign="top" align="center"><b>Required</b></td>
</tr>
<tr>
<td valign="top">destfile</td>
<td valign="top">the tar-file to create.</td>
<td align="center" valign="top">Yes</td>
</tr>
<tr>
<td valign="top">basedir</td>
<td valign="top">the directory from which to tar the files.</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">longfile</td>
<td valign="top">Determines how long files (>100 chars) are to be
handled. Allowable values are "truncate", "fail",
"warn", "omit", "gnu" and "posix". Default is
"warn".</td>
<td valign="top" align="center">No</td>
</tr>
<tr>
<td valign="top">includes</td>
<td valign="top">comma- or space-separated list of patterns of files that must be
included. All files are included when omitted.</td>
<td valign="top" align="center">No</td>
</tr>
<tr>
<td valign="top">includesfile</td>
<td valign="top">the name of a file. Each line of this file is
taken to be an include pattern</td>
<td valign="top" align="center">No</td>
</tr>
<tr>
<td valign="top">excludes</td>
<td valign="top">comma- or space-separated list of patterns of files that must be
excluded. No files (except default excludes) are excluded when omitted.</td>
<td valign="top" align="center">No</td>
</tr>
<tr>
<td valign="top">excludesfile</td>
<td valign="top">the name of a file. Each line of this file is
taken to be an exclude pattern</td>
<td valign="top" align="center">No</td>
</tr>
<tr>
<td valign="top">defaultexcludes</td>
<td valign="top">indicates whether default excludes should be used or not
("yes"/"no"). Default excludes are used when omitted.</td>
<td valign="top" align="center">No</td>
</tr>
<tr>
<td valign="top">compression</td>
<td valign="top">compression method. Allowable values are
"none", "gzip" and "bzip2". Default is
"none".</td>
<td valign="top" align="center">No</td>
</tr>
<tr>
<td valign="top">encoding</td>
<td valign="top">The character encoding to use for filenames
inside the tar file. For a list of possible values see the <a
href="http://docs.oracle.com/javase/7/docs/technotes/guides/intl/encoding.doc.html">Supported Encodings</a>.<br/>
Defaults to the platform's default character encoding.
<em>Since Ant 1.9.5</em>
<td align="center" valign="top">No</td>
</tr>
</table>
<h3>Nested Elements</h3>
The tar task supports nested <a
href="../Types/tarfileset.html">tarfileset</a> elements. These are
extended <a href="../Types/fileset.html">FileSets</a> which,
in addition to the standard elements, support one additional
attributes
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td valign="top"><b>Attribute</b></td>
<td valign="top"><b>Description</b></td>
<td valign="top" align="center"><b>Required</b></td>
</tr>
<tr>
<td valign="top">preserveLeadingSlashes</td>
<td valign="top">Indicates whether leading `/'s should
be preserved in the file names. Default is <code>false</code>.</td>
<td align="center" valign="top">No</td>
</tr>
</table>
<h4>any other resource collection</h4>
<p><a href="../Types/resources.html#collection">Resource
Collection</a>s are used to select groups of files to archive.</p>
<p>Prior to Apache Ant 1.7 only <code><fileset></code> has been
supported as a nested element.</p>
<h3>Examples</h3>
<pre>
<tar destfile="${dist}/manual.tar" basedir="htdocs/manual"/>
<gzip destfile="${dist}/manual.tar.gz" src="${dist}/manual.tar"/></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>
<tar destfile="${dist}/manual.tar"
basedir="htdocs/manual"
excludes="mydocs/**, **/todo.html"
/></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>
<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>
<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>
<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>
</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 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>
<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>
<pre>
<tar destfile="release.tar.gz" compression="gzip">
<zipfileset src="release.zip"/>
</tar>
</pre>
<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>
<p><strong>Note:</strong>
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.
</p>
</body>
</html>
|
