Unjar/Untar/Unwar/Unzip

Description

Unzips a zip-, war-, or jar file.

PatternSets are used to select files to extract from the archive. If no patternset is used, all files are extracted.

resource collections 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 fileset, filelist, path, and files. Untar supports arbitrary resource collections. Prior to Apache Ant 1.7 only fileset has been supported as a nested element.

You can define filename transformations by using a nested mapper element. The default mapper is the identity mapper.

File permissions will not be restored on extracted files.

The untar task recognizes the long pathname entries used by GNU tar.

Please note 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.

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.

Parameters

Attribute Description Required
src archive file to expand. Yes, unless filesets are used
dest directory where to store the expanded files. Yes
overwrite Overwrite files, even if they are newer than the corresponding entries in the archive (true|false). No; default is true
compression Note: This attribute is only available for the untar task.
compression method. Allowable values are none, gzip, xz and bzip2.		 No; default is none
encoding The character encoding that has been used for filenames inside the zip file. For a list of possible values see the Supported Encodings.
Use the magic value native-encoding for default JVM character encoding.
See also the discussion in the zip task page		 No; defaults to UTF8 for unzip and default JVM character encoding for untar task
failOnEmptyArchive whether trying to extract an empty archive is an error. since Ant 1.8.0 No; defaults to false
stripAbsolutePathSpec whether Ant should remove leading / or \ characters from the extracted file name before extracting it. Note that this changes the entry name before applying include/exclude patterns and before using the nested mappers (if any). since Ant 1.8.0 No; defaults to true since Ant 1.10.4 (used to default to false prior to that)
scanForUnicodeExtraFields Note: This attribute is not available for the untar task.
If the archive contains Unicode extra fields then use them to set the file names, ignoring the specified encoding.
See also the discussion in the zip task page		 No; defaults to true
allowFilesToEscapeDest Whether to allow the extracted file or directory to be outside of the dest directory. since Ant 1.10.4 No, defaults to false unless stripAbsolutePathSpec is false and the entry's name starts with a leading path spec.

Examples

<unzip src="${tomcat_src}/tools-src.zip" dest="${tools.home}"/>
<gunzip src="tools.tar.gz"/>
<untar src="tools.tar" dest="${tools.home}"/>
<unzip src="${tomcat_src}/tools-src.zip"
       dest="${tools.home}">
    <patternset>
        <include name="**/*.java"/>
        <exclude name="**/Test*.java"/>
    </patternset>
</unzip>
<unzip dest="${tools.home}">
    <patternset>
        <include name="**/*.java"/>
        <exclude name="**/Test*.java"/>
    </patternset>
    <fileset dir=".">
        <include name="**/*.zip"/>
        <exclude name="**/tmp*.zip"/>
    </fileset>
</unzip>
<unzip src="apache-ant-bin.zip" dest="${tools.home}">
    <patternset>
        <include name="apache-ant/lib/ant.jar"/>
    </patternset>
    <mapper type="flatten"/>
</unzip>

Extract all images from ant.jar which are stored in the images directory of the jar file (or somewhere under it). While extracting the directory structure (images) will be preserved.

<unzip src="${ant.home}/lib/ant.jar" dest="...">
  <patternset>
    <include name="images/"/>
  </patternset>
</unzip>

Extract two files, ant_logo_large.gif and LICENSE.txt, from ant.jar. More exactly: extract all files with these names from anywhere in the source file. While extracting the directory structure will be preserved.

<unzip src="${ant.home}/lib/ant.jar" dest="...">
  <patternset>
    <include name="**/ant_logo_large.gif"/>
    <include name="**/LICENSE.txt"/>
  </patternset>
</unzip>

Related tasks

The task

<unzip src="some-archive" dest="some-dir">
  <patternset>
    <include name="some-pattern"/>
  </patternset>
  <mapper type="some-mapper"/>
</unzip>

is identical to

<copy todir="some-dir" preservelastmodified="true">
  <zipfileset src="some-archive">
    <patternset>
      <include name="some-pattern"/>
    </patternset>
  </zipfileset>
  <mapper type="some-mapper"/>
</copy>

The same is also true for <untar> and <tarfileset>. <copy> offers additional features like filtering files on the fly, allowing a file to be mapped to multiple destinations or a configurable file system timestamp granularity.

"Delete" files from a zipfile.

<zip destfile="new.jar">
  <zipfileset src="old.jar">
    <exclude name="do/not/include/this/class"/>
  </zipfileset>
</zip>