2018-12-21 11:20:43 +01:00
|
|
|
<!DOCTYPE html>
|
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
|
|
|
|
|
|
2019-05-25 13:41:47 +02:00
|
|
|
https://www.apache.org/licenses/LICENSE-2.0
|
2006-09-11 04:19:00 +00:00
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
-->
|
2018-12-21 11:20:43 +01:00
|
|
|
<html lang="en">
|
2001-02-13 12:32:01 +00:00
|
|
|
|
|
|
|
|
<head>
|
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>Unzip Task</title>
|
2001-02-13 12:32:01 +00:00
|
|
|
</head>
|
|
|
|
|
|
|
|
|
|
<body>
|
|
|
|
|
|
2018-01-22 23:52:21 +01:00
|
|
|
<h2 id="unzip">Unjar/Untar/Unwar/Unzip</h2>
|
2001-02-13 12:32:01 +00:00
|
|
|
<h3>Description</h3>
|
2005-02-07 23:42:21 +00:00
|
|
|
<p>Unzips a zip-, war-, or jar file.</p>
|
2018-02-28 07:58:59 +01:00
|
|
|
<p><a href="../Types/patternset.html">PatternSet</a>s are used to select files to
|
|
|
|
|
extract <em>from</em> the archive. If no patternset is used, all files are extracted.</p>
|
|
|
|
|
|
2018-03-05 17:35:30 +01:00
|
|
|
<p><a href="../Types/resources.html#collection">resource collections</a> may be used to select
|
2018-02-28 07:58:59 +01:00
|
|
|
archived files to perform unarchival upon. Only file system based resource collections are
|
|
|
|
|
supported by <code>Unjar</code>/<code>Unwar</code>/<code>Unzip</code>, 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>. <code>Untar</code> supports arbitrary
|
|
|
|
|
resource collections. Prior to Apache Ant 1.7 only <code>fileset</code> 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>
|
2001-02-13 12:32:01 +00:00
|
|
|
<p>File permissions will not be restored on extracted files.</p>
|
2018-02-28 07:58:59 +01:00
|
|
|
<p>The <code>untar</code> task recognizes the long pathname entries used by GNU tar.<p>
|
2008-07-11 09:25:30 +00:00
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<p><strong>Please note</strong> 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>
|
2008-07-11 09:25:30 +00:00
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<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 <code>unzip</code> 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>
|
2008-07-11 09:25:30 +00:00
|
|
|
|
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-05-15 10:29:27 +02:00
|
|
|
<th scope="col">Attribute</th>
|
|
|
|
|
<th scope="col">Description</th>
|
|
|
|
|
<th scope="col">Required</th>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>src</td>
|
|
|
|
|
<td>archive file to expand.</td>
|
|
|
|
|
<td>Yes, unless filesets are used</td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>dest</td>
|
|
|
|
|
<td>directory where to store the expanded files.</td>
|
|
|
|
|
<td>Yes</td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
2001-07-27 06:52:51 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>overwrite</td>
|
|
|
|
|
<td>Overwrite files, even if they are newer than the corresponding entries in the archive
|
|
|
|
|
(<q>true|false</q>).</td>
|
|
|
|
|
<td>No; default is <q>true</q></td>
|
2001-07-27 06:52:51 +00:00
|
|
|
</tr>
|
2002-04-24 03:09:06 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>compression</td>
|
2018-03-02 08:23:45 +01:00
|
|
|
<td><strong>Note</strong>: This attribute is only available for the <code>untar</code> task.<br/>
|
2018-02-28 07:58:59 +01:00
|
|
|
compression method. Allowable values are <q>none</q>, <q>gzip</q>, <q>xz</q>
|
|
|
|
|
and <q>bzip2</q>.</td>
|
|
|
|
|
<td>No; default is <q>none</q></td>
|
2002-04-24 03:09:06 +00:00
|
|
|
</tr>
|
2003-07-03 13:02:01 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>encoding</td>
|
|
|
|
|
<td>The character encoding that has been used for filenames inside the zip file. For a list of
|
|
|
|
|
possible values see
|
2018-03-08 07:43:53 +01:00
|
|
|
the <a href="https://docs.oracle.com/javase/8/docs/technotes/guides/intl/encoding.doc.html"
|
|
|
|
|
target="_top">Supported Encodings</a>.<br/> Use the magic value <q>native-encoding</q> for
|
|
|
|
|
default JVM character encoding.<br/> See also the <a href="zip.html#encoding">discussion in
|
|
|
|
|
the zip task page</a></td>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>No; defaults to <q>UTF8</q> for <code>unzip</code> and default JVM character encoding
|
|
|
|
|
for <code>untar</code> task</td>
|
2003-07-03 13:02:01 +00:00
|
|
|
</tr>
|
2008-07-17 14:23:44 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>failOnEmptyArchive</td>
|
|
|
|
|
<td>whether trying to extract an empty archive is an error. <em>since Ant 1.8.0</em></td>
|
|
|
|
|
<td>No; defaults to <q>false</q></td>
|
2008-07-17 14:23:44 +00:00
|
|
|
</tr>
|
2008-07-18 10:51:30 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>stripAbsolutePathSpec</td>
|
|
|
|
|
<td>whether Ant should remove leading <q>/</q> or <q>\</q> characters from the extracted file
|
|
|
|
|
name before extracting it. Note that this changes the entry name before
|
|
|
|
|
applying <code>include</code>/<code>exclude</code> patterns and before using the nested
|
|
|
|
|
mappers (if any). <em>since Ant 1.8.0</em></td>
|
2018-05-05 19:00:17 +02:00
|
|
|
<td>No; defaults to <q>true</q> <em>since Ant 1.10.4</em>
|
|
|
|
|
(used to default to <q>false</q> prior to that)</td>
|
2008-07-18 10:51:30 +00:00
|
|
|
</tr>
|
2009-02-27 17:00:59 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>scanForUnicodeExtraFields</td>
|
2018-03-02 08:23:45 +01:00
|
|
|
<td><strong>Note</strong>: This attribute is not available for the <code>untar</code> task.<br/>
|
2018-02-28 07:58:59 +01:00
|
|
|
If the archive contains Unicode extra fields then use them to set the file names, ignoring the
|
2018-05-05 19:00:17 +02:00
|
|
|
specified encoding.<br/>See also the <a href="zip.html#encoding">discussion in the zip task
|
2018-02-28 07:58:59 +01:00
|
|
|
page</a></td>
|
|
|
|
|
<td>No; defaults to <q>true</q></td>
|
2009-02-27 17:00:59 +00:00
|
|
|
</tr>
|
2018-04-21 20:01:02 +02:00
|
|
|
<tr>
|
2018-04-21 20:01:22 +02:00
|
|
|
<td>allowFilesToEscapeDest</td>
|
2018-04-21 20:32:50 +02:00
|
|
|
<td>Whether to allow the extracted file or directory to be outside of the dest
|
|
|
|
|
directory. <em>since Ant 1.10.4</em></td>
|
2018-04-30 15:37:58 +02:00
|
|
|
<td>No, defaults to <q>false</q> unless <var>stripAbsolutePathSpec</var> is <q>false</q> and the
|
2018-04-21 20:32:50 +02:00
|
|
|
entry's name starts with a leading path spec.</td>
|
2018-04-21 20:01:02 +02:00
|
|
|
</tr>
|
2001-02-13 12:32:01 +00:00
|
|
|
</table>
|
|
|
|
|
<h3>Examples</h3>
|
2018-02-28 07:58:59 +01:00
|
|
|
<pre><unzip src="${tomcat_src}/tools-src.zip" dest="${tools.home}"/></pre>
|
2005-03-10 13:01:55 +00:00
|
|
|
<pre>
|
|
|
|
|
<gunzip src="tools.tar.gz"/>
|
2018-02-28 07:58:59 +01:00
|
|
|
<untar src="tools.tar" dest="${tools.home}"/></pre>
|
2005-03-10 13:01:55 +00:00
|
|
|
<pre>
|
2001-11-21 07:31:01 +00:00
|
|
|
<unzip src="${tomcat_src}/tools-src.zip"
|
2001-11-21 22:36:12 +00:00
|
|
|
dest="${tools.home}">
|
2001-11-21 07:31:01 +00:00
|
|
|
<patternset>
|
|
|
|
|
<include name="**/*.java"/>
|
|
|
|
|
<exclude name="**/Test*.java"/>
|
2002-06-01 12:26:43 +00:00
|
|
|
</patternset>
|
2018-02-28 07:58:59 +01:00
|
|
|
</unzip></pre>
|
2005-03-10 13:01:55 +00:00
|
|
|
<pre>
|
2001-11-21 22:36:12 +00:00
|
|
|
<unzip dest="${tools.home}">
|
2001-11-21 07:31:01 +00:00
|
|
|
<patternset>
|
|
|
|
|
<include name="**/*.java"/>
|
|
|
|
|
<exclude name="**/Test*.java"/>
|
2002-06-01 12:26:43 +00:00
|
|
|
</patternset>
|
2001-11-21 07:31:01 +00:00
|
|
|
<fileset dir=".">
|
|
|
|
|
<include name="**/*.zip"/>
|
|
|
|
|
<exclude name="**/tmp*.zip"/>
|
2002-06-01 12:26:43 +00:00
|
|
|
</fileset>
|
2018-02-28 07:58:59 +01:00
|
|
|
</unzip></pre>
|
2005-03-10 13:01:55 +00:00
|
|
|
<pre>
|
2004-10-30 19:44:02 +00:00
|
|
|
<unzip src="apache-ant-bin.zip" dest="${tools.home}">
|
|
|
|
|
<patternset>
|
|
|
|
|
<include name="apache-ant/lib/ant.jar"/>
|
|
|
|
|
</patternset>
|
|
|
|
|
<mapper type="flatten"/>
|
2018-02-28 07:58:59 +01:00
|
|
|
</unzip></pre>
|
2005-10-19 18:37:15 +00:00
|
|
|
|
2018-05-15 09:51:58 +02:00
|
|
|
<p>Extract all images from <samp>ant.jar</samp> which are stored in the <samp>images</samp>
|
|
|
|
|
directory of the jar file (or somewhere under it). While extracting the directory structure
|
|
|
|
|
(<samp>images</samp>) will be preserved.</p>
|
|
|
|
|
<pre>
|
|
|
|
|
<unzip src="${ant.home}/lib/ant.jar" dest="...">
|
|
|
|
|
<patternset>
|
|
|
|
|
<include name="images/"/>
|
|
|
|
|
</patternset>
|
|
|
|
|
</unzip></pre>
|
|
|
|
|
|
|
|
|
|
<p>Extract two files, <samp>ant_logo_large.gif</samp> and <samp>LICENSE.txt</samp>,
|
|
|
|
|
from <samp>ant.jar</samp>. More exactly: extract all files with these names from anywhere in the
|
|
|
|
|
source file. While extracting the directory structure will be preserved.</p>
|
|
|
|
|
<pre>
|
|
|
|
|
<unzip src="${ant.home}/lib/ant.jar" dest="...">
|
|
|
|
|
<patternset>
|
|
|
|
|
<include name="**/ant_logo_large.gif"/>
|
|
|
|
|
<include name="**/LICENSE.txt"/>
|
|
|
|
|
</patternset>
|
|
|
|
|
</unzip></pre>
|
|
|
|
|
|
2005-10-19 18:37:15 +00:00
|
|
|
<h3>Related tasks</h3>
|
|
|
|
|
|
2018-05-15 09:51:58 +02:00
|
|
|
<p>The task</p>
|
|
|
|
|
|
2005-10-19 18:37:15 +00:00
|
|
|
<pre>
|
2006-05-26 22:37:27 +00:00
|
|
|
<unzip src="some-archive" dest="some-dir">
|
2005-10-19 18:37:15 +00:00
|
|
|
<patternset>
|
|
|
|
|
<include name="some-pattern"/>
|
|
|
|
|
</patternset>
|
|
|
|
|
<mapper type="some-mapper"/>
|
2018-02-28 07:58:59 +01:00
|
|
|
</unzip></pre>
|
2005-10-19 18:37:15 +00:00
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<p>is identical to</p>
|
2005-10-19 18:37:15 +00:00
|
|
|
|
|
|
|
|
<pre>
|
2006-05-26 22:37:27 +00:00
|
|
|
<copy todir="some-dir" preservelastmodified="true">
|
2005-10-19 18:37:15 +00:00
|
|
|
<zipfileset src="some-archive">
|
|
|
|
|
<patternset>
|
|
|
|
|
<include name="some-pattern"/>
|
|
|
|
|
</patternset>
|
|
|
|
|
</zipfileset>
|
|
|
|
|
<mapper type="some-mapper"/>
|
2018-02-28 07:58:59 +01:00
|
|
|
</copy></pre>
|
2005-10-19 18:37:15 +00:00
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<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>
|
2005-10-19 18:37:15 +00:00
|
|
|
|
2018-05-15 09:51:58 +02:00
|
|
|
<p>"Delete" files from a zipfile.</p>
|
|
|
|
|
|
2006-10-24 15:38:28 +00:00
|
|
|
<pre><zip destfile="new.jar">
|
|
|
|
|
<zipfileset src="old.jar">
|
|
|
|
|
<exclude name="do/not/include/this/class"/>
|
|
|
|
|
</zipfileset>
|
2018-02-28 07:58:59 +01:00
|
|
|
</zip></pre>
|
|
|
|
|
|
2001-02-13 12:32:01 +00:00
|
|
|
</body>
|
|
|
|
|
</html>
|
