# Ant User Manual

## Zip

### Description

Creates a zipfile.

The basedir attribute is the reference directory from where to zip.

Note that file permissions will not be stored in the resulting zipfile.

It is possible to refine the set of files that are being zipped. This can be done with the includes, includesfile, excludes, excludesfile and defaultexcludes attributes. With the includes or includesfile attribute you specify the files you want to have included by using patterns. The exclude or excludesfile attribute is used to specify the files you want to have excluded. This is also done with patterns. And finally with the defaultexcludes attribute, you can specify whether you want to use default exclusions or not. See the section on directory based tasks, on how the inclusion/exclusion of files works, and how to write patterns.

This task forms an implicit FileSet and supports all attributes of `<fileset>` (`dir` becomes `basedir`) as well as the nested `<include>`, `<exclude>` and `<patternset>` elements.

Or, you may place within it nested file sets, or references to file sets. In this case `basedir` is optional; the implicit file set is only used if `basedir` is set. You may use any mixture of the implicit file set (with `basedir` set, and optional attributes like `includes` and optional subelements like `<include>`); explicit nested `<fileset>` elements so long as at least one fileset total is specified. The ZIP file will only reflect the relative paths of files within each fileset. The Zip task and its derivatives know a special form of a fileset named zipfileset that has additional attributes (described below).

The `whenempty` parameter controls what happens when no files match. If `skip` (the default), the ZIP is not created and a warning is issued. If `fail`, the ZIP is not created and the build is halted with an error. If `create`, an empty ZIP file (explicitly zero entries) is created, which should be recognized as such by compliant ZIP manipulation tools.

### Parameters

Attribute | Description | Required
zipfile | the zip-file to create. | Yes
basedir | the directory from which to zip the files. | No
compress | Not only store data but also compress them, defaults to true | No
includes | comma separated list of patterns of files that must be included. All files are included when omitted. | No
includesfile | the name of a file. Each line of this file is taken to be an include pattern | No
excludes | comma separated list of patterns of files that must be excluded. No files (except default excludes) are excluded when omitted. | No
excludesfile | the name of a file. Each line of this file is taken to be an exclude pattern | No
defaultexcludes | indicates whether default excludes should be used or not ("yes"/"no"). Default excludes are used when omitted. | No
whenempty | Behavior when no files match. | No

### Parameters specified as nested elements

#### fileset

The zip task supports any number of nested `<fileset>` elements to specify the files to be included in the archive.

#### zipfileset

A `<zipfileset>` has three additional attributes: prefix, fullpath, and src. The prefix and fullpath attributes modify the location of the files when they are placed inside the archive. If the prefix attribute is set, all files in the fileset are prefixed with that path in the archive. If the fullpath attribute is set, the file described by the fileset is placed at that exact location in the archive. (The fullpath attribute can only be set for filesets that represent a single file. The prefix and fullpath attributes cannot both be set on the same fileset.) The src attribute may be used in place of the dir attribute to specify a zip file whose contents will be extracted and included in the archive. As with directories, include and exclude patterns may be used to specify a subset of the zip file for inclusion in the archive.

### Examples

      <zip zipfile="${dist}/manual.zip"
           basedir="htdocs/manual"
      />

zips all files in the `htdocs/manual` directory into a file called `manual.zip` in the `${dist}` directory.

      <zip zipfile="${dist}/manual.zip"
           basedir="htdocs/manual"
           excludes="mydocs/**, **/todo.html"
      />

zips all files in the `htdocs/manual` directory. Files in the directory `mydocs`, or files with the name `todo.html` are excluded.

      <zip zipfile="${dist}/manual.zip"
           basedir="htdocs/manual"
           includes="api/**/*.html"
           excludes="**/todo.html"
      />

zips all files in the `htdocs/manual` directory. Only html files under the directory `api` are zipped, and files with the name `todo.html` are excluded.

      <zip zipfile="${dist}/manual.zip">
        <fileset dir="htdocs/manual"/>
        <fileset dir="." includes="ChangeLog.txt"/>
      </zip>

zips all files in the `htdocs/manual` directory, and also adds the file `ChangeLog.txt` in the current directory. `ChangeLog.txt` will be added to the top of the ZIP file, just as if it had been located at `htdocs/manual/ChangeLog.txt`.

      <zip zipfile="${dist}/manual.zip">
        <zipfileset dir="htdocs/manual" prefix="docs/user-guide"/>
        <zipfileset dir="." includes="ChangeLog27.txt" fullpath="docs/ChangeLog.txt"/>
        <zipfileset src="examples.zip" includes="**/*.html" prefix="docs/examples"/>
      </zip>

zips all files in the `htdocs/manual` directory into the `docs/user-guide` directory in the archive, adds the file `ChangeLog27.txt` in the current directory as `docs/ChangeLog.txt`, and includes all the html files in `examples.zip` under `docs/examples`. The archive might end up containing the files:

        docs/user-guide/html/index.html
        docs/ChangeLog.txt
        docs/examples/index.html

Copyright © 2000,2001 Apache Software Foundation. All rights Reserved.