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
|
<!--
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>Unzip Task</title>
</head>
<body>
<h2><a name="unzip">Unjar/Untar/Unwar/Unzip</a></h2>
<h3>Description</h3>
<p>Unzips a zip-, war-, or jar file.</p>
<p><a href="../Types/patternset.html">PatternSet</a>s are used to select files to extract
<I>from</I> the archive. If no patternset is used, all files are extracted.
</p>
<p><a href="../Types/resources.html#collection">Resource
Collection</a>s may be used to select archived files to perform
unarchival upon. Only file system based resource collections are
supported by Unjar/Unwar/Unzip, this includes <a
href="../Types/fileset.html">fileset</a>, <a
href="../Types/filelist.html">filelist</a>, <a
href="../using.html#path">path</a>, and <a
href="../Types/resources.html#files">files</a>.
Untar supports arbitrary resource collections.
Prior to Apache Ant 1.7 only fileset has been supported as a nested element.</p>
<p>You can define filename transformations by using a nested <a href="../Types/mapper.html">mapper</a> element. The default mapper is the
<a href="../Types/mapper.html#identity-mapper">identity mapper</a>.
</p>
<p>File permissions will not be restored on extracted files.</p>
<p>The untar task recognizes the long pathname entries used by GNU tar.<p>
<p><b>Please note</b> that different ZIP tools handle timestamps
differently when it comes to applying timezone offset calculations of
files. Some ZIP libraries will store the timestamps as they've been
read from the filesystem while others will modify the timestamps both
when reading and writing the files to make all timestamps use the same
timezone. A ZIP archive created by one library may extract files with
"wrong timestamps" when extracted by another library.</p>
<p>Ant's ZIP classes use the same algorithm as the InfoZIP tools and
zlib (timestamps get adjusted), Windows' "compressed folders" function
and WinZIP don't change the timestamps. This means that using the
unzip task on files created by Windows' compressed folders function
may create files with timestamps that are "wrong", the same is true if
you use Windows' functions to extract an Ant generated ZIP
archive.</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 align="center" valign="top"><b>Required</b></td>
</tr>
<tr>
<td valign="top">src</td>
<td valign="top">archive file to expand.</td>
<td align="center" valign="top">Yes, if filesets are not used.</td>
</tr>
<tr>
<td valign="top">dest</td>
<td valign="top">directory where to store the expanded files.</td>
<td align="center" valign="top">Yes</td>
</tr>
<tr>
<td valign="top">overwrite</td>
<td valign="top">Overwrite files, even if they are newer than the
corresponding entries in the archive (true or false, default is
true).</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">compression</td>
<td valign="top"><b>Note:</b> This attribute is only available for
the <code>untar</code> task.<br>
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 that has been used for filenames
inside the zip 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 "UTF8" for the <code>unzip</code> and the
platform's default encoding for the <code>untar</code> task. Use
the magic value
<code>native-encoding</code> for the platform's default character
encoding.
<br/>See also the <a href="zip.html#encoding">discussion in the
zip task page</a></td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">failOnEmptyArchive</td>
<td valign="top">whether trying to extract an empty archive is an
error. <em>since Ant 1.8.0</em></td>
<td valign="top" align="center">No, defaults to false</td>
</tr>
<tr>
<td valign="top">stripAbsolutePathSpec</td>
<td valign="top">whether Ant should remove leading '/' or '\'
characters from the extracted file name before extracting it.
Note that this changes the entry's name before applying
include/exclude patterns and before using the nested mappers (if
any). <em>since Ant 1.8.0</em></td>
<td valign="top" align="center">No, defaults to false</td>
</tr>
<tr>
<td valign="top">scanForUnicodeExtraFields</td>
<td valign="top"><b>Note:</b> This attribute is not available for
the <code>untar</code> task.<br>
If the archive contains uncode extra fields then use them to set
the file names, ignoring the specified encoding.
<br/>See also the <a href="zip.html#encoding">discussion in the
zip task page</a></td>
<td align="center" valign="top">No, defaults to true</td>
</tr>
</table>
<h3>Examples</h3>
<pre>
<unzip src="${tomcat_src}/tools-src.zip" dest="${tools.home}"/>
</pre>
<p>
<pre>
<gunzip src="tools.tar.gz"/>
<untar src="tools.tar" dest="${tools.home}"/>
</pre>
<pre>
<unzip src="${tomcat_src}/tools-src.zip"
dest="${tools.home}">
<patternset>
<include name="**/*.java"/>
<exclude name="**/Test*.java"/>
</patternset>
</unzip>
</pre>
<p>
<pre>
<unzip dest="${tools.home}">
<patternset>
<include name="**/*.java"/>
<exclude name="**/Test*.java"/>
</patternset>
<fileset dir=".">
<include name="**/*.zip"/>
<exclude name="**/tmp*.zip"/>
</fileset>
</unzip>
</pre>
<p>
<pre>
<unzip src="apache-ant-bin.zip" dest="${tools.home}">
<patternset>
<include name="apache-ant/lib/ant.jar"/>
</patternset>
<mapper type="flatten"/>
</unzip>
</pre>
<h3>Related tasks</h3>
<pre>
<unzip src="some-archive" dest="some-dir">
<patternset>
<include name="some-pattern"/>
</patternset>
<mapper type="some-mapper"/>
</unzip>
</pre>
is identical to
<pre>
<copy todir="some-dir" preservelastmodified="true">
<zipfileset src="some-archive">
<patternset>
<include name="some-pattern"/>
</patternset>
</zipfileset>
<mapper type="some-mapper"/>
</copy>
</pre>
<p>The same is also true for <code><untar></code> and
<code><tarfileset></code>. <code><copy></code> offers
additional features like <a href="../Types/filterchain.html">filtering files</a> on the fly,
allowing a file to be mapped to multiple destinations or a
configurable file system timestamp granularity.</p>
<pre><zip destfile="new.jar">
<zipfileset src="old.jar">
<exclude name="do/not/include/this/class"/>
</zipfileset>
</zip>
</pre>
<p>"Deletes" files from a zipfile.</p>
<pre>
<unzip src="${ant.home}/lib/ant.jar" dest="...">
<patternset>
<include name="images/"/>
</patternset>
</unzip>
</pre>
<p>This extracts all images from <tt>ant.jar</tt> which are stored in the <tt>images</tt> directory
of the Jar (or somewhere under it). While extracting the directory structure (<tt>images</tt>)
will be taken.</p>
<pre>
<unzip src="${ant.home}/lib/ant.jar" dest="...">
<patternset>
<include name="**/ant_logo_large.gif"/>
<include name="**/LICENSE.txt"/>
</patternset>
</unzip>
</pre>
<p>This extracts the two files <tt>ant_logo_large.gif</tt> and <tt>LICENSE.txt</tt> from the
<tt>ant.jar</tt>. More exactly: it extracts all files with these names from anywhere in the source file. While extracting the directory structure will be taken.</p>
</body>
</html>
|
