Merge branch '1.9.x'
Project: http://git-wip-us.apache.org/repos/asf/ant/repo Commit: http://git-wip-us.apache.org/repos/asf/ant/commit/d4cc7cf0 Tree: http://git-wip-us.apache.org/repos/asf/ant/tree/d4cc7cf0 Diff: http://git-wip-us.apache.org/repos/asf/ant/diff/d4cc7cf0 Branch: refs/heads/master Commit: d4cc7cf0a9537e79509cf22dd9b030dfc3bec08f Parents: 0b3e006 857095d Author: Stefan Bodewig <[email protected]> Authored: Sat May 5 17:30:12 2018 +0200 Committer: Stefan Bodewig <[email protected]> Committed: Sat May 5 17:30:12 2018 +0200 ---------------------------------------------------------------------- WHATSNEW | 4 +++- manual/Tasks/unzip.html | 3 ++- src/main/org/apache/tools/ant/taskdefs/Expand.java | 2 +- src/tests/antunit/taskdefs/unzip-test.xml | 10 +++++----- 4 files changed, 11 insertions(+), 8 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/ant/blob/d4cc7cf0/WHATSNEW ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/ant/blob/d4cc7cf0/manual/Tasks/unzip.html ---------------------------------------------------------------------- diff --cc manual/Tasks/unzip.html index 8b67f3b,dbf4a16..7076e5a --- a/manual/Tasks/unzip.html +++ b/manual/Tasks/unzip.html @@@ -24,106 -24,129 +24,107 @@@ <body> -<h2><a name="unzip">Unjar/Untar/Unwar/Unzip</a></h2> +<h2 id="unzip">Unjar/Untar/Unwar/Unzip</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><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> + +<p><a href="../Types/resources.html#collection">resource collections</a> may be used to select +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> <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>The <code>untar</code> 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> +<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> +<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> <h3>Parameters</h3> -<table border="1" cellpadding="2" cellspacing="0"> +<table class="attr"> <tr> - <td valign="top"><b>Attribute</b></td> - <td valign="top"><b>Description</b></td> - <td align="center" valign="top"><b>Required</b></td> + <th>Attribute</th> + <th>Description</th> + <th>Required</th> </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> + <td>src</td> + <td>archive file to expand.</td> + <td>Yes, unless filesets are 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> + <td>dest</td> + <td>directory where to store the expanded files.</td> + <td>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> + <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> </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> + <td>compression</td> + <td><strong>Note</strong>: This attribute is only available for the <code>untar</code> task.<br/> + 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> </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> + <td>encoding</td> + <td>The character encoding that has been used for filenames inside the zip file. For a list of + possible values see + 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> + <td>No; defaults to <q>UTF8</q> for <code>unzip</code> and default JVM character encoding + for <code>untar</code> task</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> + <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> </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 true since 1.9.12 - (used to defaukt to false prior to that)</td> + <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> - <td>No; defaults to <q>false</q></td> ++ <td>No; defaults to <q>true</q> since 1.10.4 ++ (used to defaukt to <q>false</q> prior to that)</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> + <td>scanForUnicodeExtraFields</td> + <td><strong>Note</strong>: This attribute is not available for the <code>untar</code> task.<br/> + If the archive contains Unicode 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>No; defaults to <q>true</q></td> </tr> <tr> - <td valign="top">allowFilesToEscapeDest</td> - <td valign="top">Whether to allow the extracted file or directory - to be outside of the dest directory. - <em>since Ant 1.9.12</em></td> - <td valign="top" align="center">No, defaults to false unless - stripAbsolutePathSpec is false and the entry's name starts with a leading - path spec.</td> + <td>allowFilesToEscapeDest</td> + <td>Whether to allow the extracted file or directory to be outside of the dest + directory. <em>since Ant 1.10.4</em></td> + <td>No, defaults to <q>false</q> unless <var>stripAbsolutePathSpec</var> is <q>false</q> and the + entry's name starts with a leading path spec.</td> </tr> </table> <h3>Examples</h3> http://git-wip-us.apache.org/repos/asf/ant/blob/d4cc7cf0/src/main/org/apache/tools/ant/taskdefs/Expand.java ----------------------------------------------------------------------
