You can not select more than 25 topics Topics must start with a chinese character,a letter or number, can include dashes ('-') and can be up to 35 characters long.

unzip.html 7.7 KiB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210
  1. <!--
  2. Licensed to the Apache Software Foundation (ASF) under one or more
  3. contributor license agreements. See the NOTICE file distributed with
  4. this work for additional information regarding copyright ownership.
  5. The ASF licenses this file to You under the Apache License, Version 2.0
  6. (the "License"); you may not use this file except in compliance with
  7. the License. You may obtain a copy of the License at
  8. http://www.apache.org/licenses/LICENSE-2.0
  9. Unless required by applicable law or agreed to in writing, software
  10. distributed under the License is distributed on an "AS IS" BASIS,
  11. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12. See the License for the specific language governing permissions and
  13. limitations under the License.
  14. -->
  15. <html>
  16. <head>
  17. <meta http-equiv="Content-Language" content="en-us">
  18. <link rel="stylesheet" type="text/css" href="../stylesheets/style.css">
  19. <title>Unzip Task</title>
  20. </head>
  21. <body>
  22. <h2><a name="unzip">Unjar/Untar/Unwar/Unzip</a></h2>
  23. <h3>Description</h3>
  24. <p>Unzips a zip-, war-, or jar file.</p>
  25. <p><a href="../CoreTypes/patternset.html">PatternSet</a>s are used to select files to extract
  26. <I>from</I> the archive. If no patternset is used, all files are extracted.
  27. </p>
  28. <p><a href="../CoreTypes/resources.html#collection">Resource
  29. Collection</a>s may be used to select archived files to perform
  30. unarchival upon. Only file system based resource collections are
  31. supported by Unjar/Unwar/Unzip, this includes <a
  32. href="../CoreTypes/fileset.html">fileset</a>, <a
  33. href="../CoreTypes/filelist.html">filelist</a>, <a
  34. href="../using.html#path">path</a>, and <a
  35. href="../CoreTypes/resources.html#files">files</a>.
  36. Untar supports arbitrary resource collections.
  37. Prior to Ant 1.7 only fileset has been supported as a nested element.</p>
  38. <p>You can define filename transformations by using a nested <a href="../CoreTypes/mapper.html">mapper</a> element. The default mapper is the
  39. <a href="../CoreTypes/mapper.html#identity-mapper">identity mapper</a>.
  40. </p>
  41. <p>File permissions will not be restored on extracted files.</p>
  42. <p>The untar task recognizes the long pathname entries used by GNU tar.<p>
  43. <p><b>Please note</b> that different ZIP tools handle timestamps
  44. differently when it comes to applying timezone offset calculations of
  45. files. Some ZIP libraries will store the timestamps as they've been
  46. read from the filesystem while others will modify the timestamps both
  47. when reading and writing the files to make all timestamps use the same
  48. timezone. A ZIP archive created by one library may extract files with
  49. "wrong timestamps" when extracted by another library.</p>
  50. <p>Ant's ZIP classes use the same algorithm as the InfoZIP tools and
  51. zlib (timestamps get adjusted), Windows' "compressed folders" function
  52. and WinZIP don't change the timestamps. This means that using the
  53. unzip task on files created by Windows' compressed folders function
  54. may create files with timestamps that are "wrong", the same is true if
  55. you use Windows' functions to extract an Ant generated ZIP
  56. archive.</p>
  57. <h3>Parameters</h3>
  58. <table border="1" cellpadding="2" cellspacing="0">
  59. <tr>
  60. <td valign="top"><b>Attribute</b></td>
  61. <td valign="top"><b>Description</b></td>
  62. <td align="center" valign="top"><b>Required</b></td>
  63. </tr>
  64. <tr>
  65. <td valign="top">src</td>
  66. <td valign="top">archive file to expand.</td>
  67. <td align="center" valign="top">Yes, if filesets are not used.</td>
  68. </tr>
  69. <tr>
  70. <td valign="top">dest</td>
  71. <td valign="top">directory where to store the expanded files.</td>
  72. <td align="center" valign="top">Yes</td>
  73. </tr>
  74. <tr>
  75. <td valign="top">overwrite</td>
  76. <td valign="top">Overwrite files, even if they are newer than the
  77. corresponding entries in the archive (true or false, default is
  78. true).</td>
  79. <td align="center" valign="top">No</td>
  80. </tr>
  81. <tr>
  82. <td valign="top">compression</td>
  83. <td valign="top"><b>Note:</b> This attribute is only available for
  84. the <code>untar</code> task.<br>
  85. compression method. Allowable values are &quot;none&quot;,
  86. &quot;gzip&quot; and &quot;bzip2&quot;. Default is
  87. &quot;none&quot;.</td>
  88. <td valign="top" align="center">No</td>
  89. </tr>
  90. <tr>
  91. <td valign="top">encoding</td>
  92. <td valign="top"><b>Note:</b> This attribute is not available for
  93. the <code>untar</code> task.<br>
  94. The character encoding that has been used for filenames
  95. inside the zip file. For a list of possible values see <a
  96. href="http://java.sun.com/j2se/1.5.0/docs/guide/intl/encoding.doc.html">http://java.sun.com/j2se/1.5.0/docs/guide/intl/encoding.doc.html</a>.<br>
  97. Defaults to &quot;UTF8&quot;, use the magic value
  98. <code>native-encoding</code> for the platform's default character
  99. encoding.</td>
  100. <td align="center" valign="top">No</td>
  101. </tr>
  102. <tr>
  103. <td valign="top">failOnEmptyArchive</td>
  104. <td valign="top">whether trying to extract an empty archive is an
  105. error. <em>since Ant 1.8.0</em></td>
  106. <td valign="top" align="center">No, defaults to false</td>
  107. </tr>
  108. <tr>
  109. <td valign="top">stripAbsolutePathSpec</td>
  110. <td valign="top">whether Ant should remove leading '/' or '\'
  111. characters from the extracted file name before extracing it.
  112. Note that this changes the entry's name before applying
  113. include/exclude patterns and before using the nested mappers (if
  114. any). <em>since Ant 1.8.0</em></td>
  115. <td valign="top" align="center">No, defaults to false</td>
  116. </tr>
  117. </table>
  118. <h3>Examples</h3>
  119. <pre>
  120. &lt;unzip src=&quot;${tomcat_src}/tools-src.zip&quot; dest=&quot;${tools.home}&quot;/&gt;
  121. </pre>
  122. <p>
  123. <pre>
  124. &lt;gunzip src=&quot;tools.tar.gz&quot;/&gt;
  125. &lt;untar src=&quot;tools.tar&quot; dest=&quot;${tools.home}&quot;/&gt;
  126. </pre>
  127. <pre>
  128. &lt;unzip src=&quot;${tomcat_src}/tools-src.zip&quot;
  129. dest=&quot;${tools.home}&quot;&gt;
  130. &lt;patternset&gt;
  131. &lt;include name=&quot;**/*.java&quot;/&gt;
  132. &lt;exclude name=&quot;**/Test*.java&quot;/&gt;
  133. &lt;/patternset&gt;
  134. &lt;/unzip&gt;
  135. </pre>
  136. <p>
  137. <pre>
  138. &lt;unzip dest=&quot;${tools.home}&quot;&gt;
  139. &lt;patternset&gt;
  140. &lt;include name=&quot;**/*.java&quot;/&gt;
  141. &lt;exclude name=&quot;**/Test*.java&quot;/&gt;
  142. &lt;/patternset&gt;
  143. &lt;fileset dir=&quot;.&quot;&gt;
  144. &lt;include name=&quot;**/*.zip&quot;/&gt;
  145. &lt;exclude name=&quot;**/tmp*.zip&quot;/&gt;
  146. &lt;/fileset&gt;
  147. &lt;/unzip&gt;
  148. </pre>
  149. <p>
  150. <pre>
  151. &lt;unzip src=&quot;apache-ant-bin.zip&quot; dest=&quot;${tools.home}&quot;&gt;
  152. &lt;patternset&gt;
  153. &lt;include name=&quot;apache-ant/lib/ant.jar&quot;/&gt;
  154. &lt;/patternset&gt;
  155. &lt;mapper type=&quot;flatten&quot;/&gt;
  156. &lt;/unzip&gt;
  157. </pre>
  158. <h3>Related tasks</h3>
  159. <pre>
  160. &lt;unzip src="some-archive" dest="some-dir"&gt;
  161. &lt;patternset&gt;
  162. &lt;include name="some-pattern"/&gt;
  163. &lt;/patternset&gt;
  164. &lt;mapper type=&quot;some-mapper&quot;/&gt;
  165. &lt;/unzip&gt;
  166. </pre>
  167. is identical to
  168. <pre>
  169. &lt;copy todir="some-dir" preservelastmodified="true"&gt;
  170. &lt;zipfileset src="some-archive"&gt;
  171. &lt;patternset&gt;
  172. &lt;include name="some-pattern"/&gt;
  173. &lt;/patternset&gt;
  174. &lt;/zipfileset&gt;
  175. &lt;mapper type=&quot;some-mapper&quot;/&gt;
  176. &lt;/copy&gt;
  177. </pre>
  178. <p>The same is also true for <code>&lt;untar&gt;</code> and
  179. <code>&lt;tarfileset&gt;</code>. <code>&lt;copy&gt;</code> offers
  180. additional features like <a href="../CoreTypes/filterchain.html">filtering files</a> on the fly,
  181. allowing a file to be mapped to multiple destinations or a
  182. configurable file system timestamp granularity.</p>
  183. <pre>&lt;zip destfile=&quot;new.jar&quot;&gt;
  184. &lt;zipfileset src=&quot;old.jar&quot;&gt;
  185. &lt;exclude name=&quot;do/not/include/this/class&quot;/&gt;
  186. &lt;/zipfileset&gt;
  187. &lt;/zip&gt;
  188. </pre>
  189. <p>&quot;Deletes&quot; files from a zipfile.</p>
  190. </body>
  191. </html>