## 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 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.

### Parameters

Attribute | Description | Required
src | archive file to expand. | Yes, if filesets are not 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 or false, default is true). | No
compression | Note: This attribute is only available for the `untar` task. compression method. Allowable values are "none", "gzip" and "bzip2". Default is "none". | No
encoding | Note: This attribute is not available for the `untar` task. The character encoding that has been used for filenames inside the zip file. For a list of possible values see http://java.sun.com/j2se/1.5.0/docs/guide/intl/encoding.doc.html. Defaults to "UTF8", use the magic value `native-encoding` for the platform's default character encoding. | No

### 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>

### Related tasks

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

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

"Deletes" files from a zipfile.