docs/manual/CoreTasks/zip.html - ant - Git at Google

 <html>

 <head>
 <meta http-equiv="Content-Language" content="en-us">
 <title>Zip Task</title>
 <link rel="stylesheet" type="text/css" href="../stylesheets/antmanual.css">
 </head>

 <body>

 <h2><a name="zip">Zip</a></h2>
 <h3>Description</h3>
 <p>Creates a zipfile.</p>
 <p>The <i>basedir</i> attribute is the reference directory from where to zip.</p>
 <p>Note that file permissions will not be stored in the resulting zipfile.</p>
 <p>It is possible to refine the set of files that are being zipped. This can be
 done with the <i>includes</i>, <i>includesfile</i>, <i>excludes</i>, <i>excludesfile</i> and <i>defaultexcludes</i>
 attributes. With the <i>includes</i> or <i>includesfile</i> attribute you specify the files you want to
 have included by using patterns. The <i>exclude</i> or <i>excludesfile</i> attribute is used to specify
 the files you want to have excluded. This is also done with patterns. And
 finally with the <i>defaultexcludes</i> attribute, you can specify whether you
 want to use default exclusions or not. See the section on <a
 href="../dirtasks.html#directorybasedtasks">directory based tasks</a>, on how the
 inclusion/exclusion of files works, and how to write patterns. </p>
 <p>This task forms an implicit <a href="../CoreTypes/fileset.html">FileSet</a> and
 supports all attributes of <code>&lt;fileset&gt;</code>
 (<code>dir</code> becomes <code>basedir</code>) as well as the nested
 <code>&lt;include&gt;</code>, <code>&lt;exclude&gt;</code> and
 <code>&lt;patternset&gt;</code> elements.</p>
 <p>Or, you may place within it nested file sets, or references to file sets.
 In this case <code>basedir</code> is optional; the implicit file set is <i>only used</i>
 if <code>basedir</code> is set. You may use any mixture of the implicit file set
 (with <code>basedir</code> set, and optional attributes like <code>includes</code>
 and optional subelements like <code>&lt;include&gt;</code>); explicit nested
 <code>&lt;fileset&gt;</code> elements so long as at least one fileset total is specified. The ZIP file will
 only reflect the relative paths of files <i>within</i> each fileset. The Zip task and its derivatives know a special form of a fileset named zipfileset that has additional attributes (described below). </p>
 <p>The Zip task also supports the merging of multiple zip files into the zip file.
 This is possible through either the <i>src</i> attribute of any nested filesets
 or by using the special nested fileset <i>zipgroupfileset</i>.</p>

 <p>The <code>update</code> parameter controls what happens if the ZIP
 file already exists. When set to <code>yes</code>, the ZIP file is
 updated with the files specified. (New files are added; old files are
 replaced with the new versions.) When set to <code>no</code> (the
 default) the ZIP file is overwritten.  Please note that ZIP files
 store file modification times with a granularity of two seconds.  If a
 file is less than two seconds newer than the entry in the archive, Ant
 will not consider it newer.</p>

 <p>The <code>whenempty</code> parameter controls what happens when no files match.
 If <code>skip</code> (the default), the ZIP is not created and a warning is issued.
 If <code>fail</code>, the ZIP is not created and the build is halted with an error.
 If <code>create</code>, an empty ZIP file (explicitly zero entries) is created,
 which should be recognized as such by compliant ZIP manipulation tools.</p>
 <p>This task will now use the platform's default character encoding
 for filenames - this is consistent with the command line ZIP tools,
 but causes problems if you try to open them from within Java and your
 filenames contain non US-ASCII characters. Use the encoding attribute
 and set it to UTF8 to create zip files that can safely be read by
 Java.</p>

 <p>Starting with Ant 1.5.2, &lt;zip&gt; can store Unix permissions
 inside the archive (see description of the filemode and dirmode
 attributes for <a href="../CoreTypes/zipfileset.html">&lt;zipfileset&gt;</a>).
 Unfortunately there is no portable way to store these permissions.
 Ant uses the algorithm used by <a href="http://www.info-zip.org">Info-Zip's</a>
 implementation of the zip and unzip commands - these are the default
 versions of zip and unzip for many Unix and Unix-like systems.</p>

 <h3>Parameters</h3>
 <table border="1" cellpadding="2" cellspacing="0">
   <tr>
     <td valign="top"><b>Attribute</b></td>
     <td valign="top"><b>Description</b></td>
     <td valign="top" align="center"><b>Required</b></td>
   </tr>
   <tr>
     <td valign="top">destfile</td>
     <td valign="top">the zip-file to create.</td>
     <td align="center" valign="top" rowspan="2">Exactly one of the two.</td>
   </tr>
   <tr>
     <td valign="top">zipfile</td>
     <td valign="top">the <i>deprecated</i> old name of destfile.</td>
   </tr>
   <tr>
     <td valign="top">basedir</td>
     <td valign="top">the directory from which to zip the files.</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
     <td valign="top">compress</td>
     <td valign="top">Not only store data but also compress them,
     defaults to true.  Unless you set the <em>keepcompression</em>
     attribute to false, this will apply to the entire archive, not
     only the files you've added while updating.</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
     <td valign="top">keepcompression</td>
     <td valign="top">For entries coming from existing archives (like
     nested <em>zipfileset</em>s or while updating the archive), keep
     the compression as it has been originally instead of using the
     <em>compress</em> attribute.  Defaults false.  <em>Since Ant
     1.6</em></td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
     <td valign="top">encoding</td>
     <td valign="top">The character encoding to use for filenames
     inside the zip file.  For a list of possible values see <a
     href="http://java.sun.com/products/jdk/1.2/docs/guide/internat/encoding.doc.html">http://java.sun.com/products/jdk/1.2/docs/guide/internat/encoding.doc.html</a>.
     Defaults to the platform's default character encoding.</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
     <td valign="top">filesonly</td>
     <td valign="top">Store only file entries, defaults to false</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
     <td valign="top">includes</td>
     <td valign="top">comma- or space-separated list of patterns of files that must be
       included. All files are included when omitted.</td>
     <td valign="top" align="center">No</td>
   </tr>
   <tr>
     <td valign="top">includesfile</td>
     <td valign="top">the name of a file. Each line of this file is
       taken to be an include pattern</td>
     <td valign="top" align="center">No</td>
   </tr>
   <tr>
     <td valign="top">excludes</td>
     <td valign="top">comma- or space-separated list of patterns of files that must be
       excluded. No files (except default excludes) are excluded when omitted.</td>
     <td valign="top" align="center">No</td>
   </tr>
   <tr>
     <td valign="top">excludesfile</td>
     <td valign="top">the name of a file. Each line of this file is
       taken to be an exclude pattern</td>
     <td valign="top" align="center">No</td>
   </tr>
   <tr>
     <td valign="top">defaultexcludes</td>
     <td valign="top">indicates whether default excludes should be used or not
       (&quot;yes&quot;/&quot;no&quot;). Default excludes are used when omitted.</td>
     <td valign="top" align="center">No</td>
   </tr>
   <tr>
     <td valign="top">update</td>
     <td valign="top">indicates whether to update or overwrite
       the destination file if it already exists.  Default is &quot;false&quot;.</td>
     <td valign="top" align="center">No</td>
   </tr>
   <tr>
     <td valign="top">whenempty</td>
     <td valign="top">behavior when no files match.  Valid values are &quot;fail&quot;, &quot;skip&quot;, and &quot;create&quot;.  Default is &quot;skip&quot;.</td>
     <td valign="top" align="center">No</td>
   </tr>
   <tr>
     <td valign="top">duplicate</td>
     <td valign="top">behavior when a duplicate file is found.  Valid values are &quot;add&quot;, &quot;preserve&quot;, and &quot;fail&quot;. The default value is &quot;add&quot;.  </td>
     <td valign="top" align="center">No</td>
   </tr>
 </table>
 <h3>Parameters specified as nested elements</h3>
 <h4>fileset</h4>
 <p>The zip task supports any number of nested <a
 href="../CoreTypes/fileset.html"><code>&lt;fileset&gt;</code></a> elements to specify
 the files to be included in the archive.</p>

 <h4>zipfileset</h4>

 <p>The zip task supports any number of nested <a
 href="../CoreTypes/zipfileset.html"><code>&lt;zipfileset&gt;</code></a> elements to specify
 the files to be included in the archive.</p>

 <h4>zipgroupfileset</h4>
 <p>A <code>&lt;zipgroupfileset&gt;</code> allows for multiple zip files to be
 merged into the archive. Each file found in this fileset is added to the archive
 the same way that <i>zipfileset src</i> files are added.</p>


 <h3>Examples</h3>
 <pre>  &lt;zip destfile=&quot;${dist}/manual.zip&quot;
        basedir=&quot;htdocs/manual&quot;
   /&gt;</pre>
 <p>zips all files in the <code>htdocs/manual</code> directory into a file called <code>manual.zip</code>
 in the <code>${dist}</code> directory.</p>
 <pre>  &lt;zip destfile=&quot;${dist}/manual.zip&quot;
        basedir=&quot;htdocs/manual&quot;
        update=&quot;true&quot;
   /&gt;</pre>
 <p>zips all files in the <code>htdocs/manual</code> directory into a file called <code>manual.zip</code>
 in the <code>${dist}</code> directory. If <code>manual.zip</code>
 doesn't exist, it is created; otherwise it is updated with the
 new/changed files.</p>
 <pre>  &lt;zip destfile=&quot;${dist}/manual.zip&quot;
        basedir=&quot;htdocs/manual&quot;
        excludes=&quot;mydocs/**, **/todo.html&quot;
   /&gt;</pre>
 <p>zips all files in the <code>htdocs/manual</code> directory. Files in the directory <code>mydocs</code>,
 or files with the name <code>todo.html</code> are excluded.</p>
 <pre>  &lt;zip destfile=&quot;${dist}/manual.zip&quot;
        basedir=&quot;htdocs/manual&quot;
        includes=&quot;api/**/*.html&quot;
        excludes=&quot;**/todo.html&quot;
   /&gt;</pre>
 <p>zips all files in the <code>htdocs/manual</code> directory. Only html files under the directory <code>api</code>
 are zipped, and files with the name <code>todo.html</code> are excluded.</p>
 <pre>  &lt;zip destfile=&quot;${dist}/manual.zip&quot;&gt;
     &lt;fileset dir=&quot;htdocs/manual&quot;/&gt;
     &lt;fileset dir=&quot;.&quot; includes=&quot;ChangeLog.txt&quot;/&gt;
   &lt;/zip&gt;</pre>
 <p>zips all files in the <code>htdocs/manual</code> directory, and also adds the file <code>ChangeLog.txt</code> in the
 current directory. <code>ChangeLog.txt</code> will be added to the top of the ZIP file, just as if
 it had been located at <code>htdocs/manual/ChangeLog.txt</code>.</p>
 <pre>  &lt;zip destfile=&quot;${dist}/manual.zip&quot;&gt;
     &lt;zipfileset dir=&quot;htdocs/manual&quot; prefix=&quot;docs/user-guide&quot;/&gt;
     &lt;zipfileset dir=&quot;.&quot; includes=&quot;ChangeLog27.txt&quot; fullpath=&quot;docs/ChangeLog.txt&quot;/&gt;
     &lt;zipfileset src=&quot;examples.zip&quot; includes=&quot;**/*.html&quot; prefix=&quot;docs/examples&quot;/&gt;
   &lt;/zip&gt;</pre>
 <p>zips all files in the <code>htdocs/manual</code> directory into the <code>docs/user-guide</code> directory
 in the archive, adds the file <code>ChangeLog27.txt</code> in the
 current directory as <code>docs/ChangeLog.txt</code>, and includes all the html files in <code>examples.zip</code>
 under <code>docs/examples</code>.  The archive might end up containing the files:</p>
 <pre><code>    docs/user-guide/html/index.html
     docs/ChangeLog.txt
     docs/examples/index.html
 </code></pre>
 <p>
 The code
 <pre>
   &lt;zip destfile=&quot;${dist}/manual.zip&quot;&gt;
     &lt;zipfileset dir=&quot;htdocs/manual&quot; prefix=&quot;docs/user-guide&quot;/&gt;
     &lt;zipgroupfileset dir=&quot;.&quot; includes=&quot;examples*.zip&quot;/&gt;
   &lt;/zip&gt;</pre>
 </pre>
 <p>
 <p>zips all files in the <code>htdocs/manual</code> directory into the <code>docs/user-guide</code> directory in the archive and includes all the files in any file that maches <code>examples*.zip</code>, such as all files within <code>examples1.zip</code> or <code>examples_for_brian.zip</code>.
 <hr>
 <p align="center">Copyright &copy; 2000-2003 Apache Software Foundation. All rights
 Reserved.</p>

 </body>
 </html>
	<html>

	<head>
	<meta http-equiv="Content-Language" content="en-us">
	<title>Zip Task</title>
	<link rel="stylesheet" type="text/css" href="../stylesheets/antmanual.css">
	</head>

	<body>

	<h2><a name="zip">Zip</a></h2>
	<h3>Description</h3>
	<p>Creates a zipfile.</p>
	<p>The <i>basedir</i> attribute is the reference directory from where to zip.</p>
	<p>Note that file permissions will not be stored in the resulting zipfile.</p>
	<p>It is possible to refine the set of files that are being zipped. This can be
	done with the <i>includes</i>, <i>includesfile</i>, <i>excludes</i>, <i>excludesfile</i> and <i>defaultexcludes</i>
	attributes. With the <i>includes</i> or <i>includesfile</i> attribute you specify the files you want to
	have included by using patterns. The <i>exclude</i> or <i>excludesfile</i> attribute is used to specify
	the files you want to have excluded. This is also done with patterns. And
	finally with the <i>defaultexcludes</i> attribute, you can specify whether you
	want to use default exclusions or not. See the section on <a
	href="../dirtasks.html#directorybasedtasks">directory based tasks</a>, on how the
	inclusion/exclusion of files works, and how to write patterns. </p>
	<p>This task forms an implicit <a href="../CoreTypes/fileset.html">FileSet</a> and
	supports all attributes of <code><fileset></code>
	(<code>dir</code> becomes <code>basedir</code>) as well as the nested
	<code><include></code>, <code><exclude></code> and
	<code><patternset></code> elements.</p>
	<p>Or, you may place within it nested file sets, or references to file sets.
	In this case <code>basedir</code> is optional; the implicit file set is <i>only used</i>
	if <code>basedir</code> is set. You may use any mixture of the implicit file set
	(with <code>basedir</code> set, and optional attributes like <code>includes</code>
	and optional subelements like <code><include></code>); explicit nested
	<code><fileset></code> elements so long as at least one fileset total is specified. The ZIP file will
	only reflect the relative paths of files <i>within</i> each fileset. The Zip task and its derivatives know a special form of a fileset named zipfileset that has additional attributes (described below). </p>
	<p>The Zip task also supports the merging of multiple zip files into the zip file.
	This is possible through either the <i>src</i> attribute of any nested filesets
	or by using the special nested fileset <i>zipgroupfileset</i>.</p>

	<p>The <code>update</code> parameter controls what happens if the ZIP
	file already exists. When set to <code>yes</code>, the ZIP file is
	updated with the files specified. (New files are added; old files are
	replaced with the new versions.) When set to <code>no</code> (the
	default) the ZIP file is overwritten. Please note that ZIP files
	store file modification times with a granularity of two seconds. If a
	file is less than two seconds newer than the entry in the archive, Ant
	will not consider it newer.</p>

	<p>The <code>whenempty</code> parameter controls what happens when no files match.
	If <code>skip</code> (the default), the ZIP is not created and a warning is issued.
	If <code>fail</code>, the ZIP is not created and the build is halted with an error.
	If <code>create</code>, an empty ZIP file (explicitly zero entries) is created,
	which should be recognized as such by compliant ZIP manipulation tools.</p>
	<p>This task will now use the platform's default character encoding
	for filenames - this is consistent with the command line ZIP tools,
	but causes problems if you try to open them from within Java and your
	filenames contain non US-ASCII characters. Use the encoding attribute
	and set it to UTF8 to create zip files that can safely be read by
	Java.</p>

	<p>Starting with Ant 1.5.2, <zip> can store Unix permissions
	inside the archive (see description of the filemode and dirmode
	attributes for <a href="../CoreTypes/zipfileset.html"><zipfileset></a>).
	Unfortunately there is no portable way to store these permissions.
	Ant uses the algorithm used by <a href="http://www.info-zip.org">Info-Zip's</a>
	implementation of the zip and unzip commands - these are the default
	versions of zip and unzip for many Unix and Unix-like systems.</p>

	<h3>Parameters</h3>
	<table border="1" cellpadding="2" cellspacing="0">
	<tr>
	<td valign="top"><b>Attribute</b></td>
	<td valign="top"><b>Description</b></td>
	<td valign="top" align="center"><b>Required</b></td>
	</tr>
	<tr>
	<td valign="top">destfile</td>
	<td valign="top">the zip-file to create.</td>
	<td align="center" valign="top" rowspan="2">Exactly one of the two.</td>
	</tr>
	<tr>
	<td valign="top">zipfile</td>
	<td valign="top">the <i>deprecated</i> old name of destfile.</td>
	</tr>
	<tr>
	<td valign="top">basedir</td>
	<td valign="top">the directory from which to zip the files.</td>
	<td align="center" valign="top">No</td>
	</tr>
	<tr>
	<td valign="top">compress</td>
	<td valign="top">Not only store data but also compress them,
	defaults to true. Unless you set the <em>keepcompression</em>
	attribute to false, this will apply to the entire archive, not
	only the files you've added while updating.</td>
	<td align="center" valign="top">No</td>
	</tr>
	<tr>
	<td valign="top">keepcompression</td>
	<td valign="top">For entries coming from existing archives (like
	nested <em>zipfileset</em>s or while updating the archive), keep
	the compression as it has been originally instead of using the
	<em>compress</em> attribute. Defaults false. <em>Since Ant
	1.6</em></td>
	<td align="center" valign="top">No</td>
	</tr>
	<tr>
	<td valign="top">encoding</td>
	<td valign="top">The character encoding to use for filenames
	inside the zip file. For a list of possible values see <a
	href="http://java.sun.com/products/jdk/1.2/docs/guide/internat/encoding.doc.html">http://java.sun.com/products/jdk/1.2/docs/guide/internat/encoding.doc.html</a>.
	Defaults to the platform's default character encoding.</td>
	<td align="center" valign="top">No</td>
	</tr>
	<tr>
	<td valign="top">filesonly</td>
	<td valign="top">Store only file entries, defaults to false</td>
	<td align="center" valign="top">No</td>
	</tr>
	<tr>
	<td valign="top">includes</td>
	<td valign="top">comma- or space-separated list of patterns of files that must be
	included. All files are included when omitted.</td>
	<td valign="top" align="center">No</td>
	</tr>
	<tr>
	<td valign="top">includesfile</td>
	<td valign="top">the name of a file. Each line of this file is
	taken to be an include pattern</td>
	<td valign="top" align="center">No</td>
	</tr>
	<tr>
	<td valign="top">excludes</td>
	<td valign="top">comma- or space-separated list of patterns of files that must be
	excluded. No files (except default excludes) are excluded when omitted.</td>
	<td valign="top" align="center">No</td>
	</tr>
	<tr>
	<td valign="top">excludesfile</td>
	<td valign="top">the name of a file. Each line of this file is
	taken to be an exclude pattern</td>
	<td valign="top" align="center">No</td>
	</tr>
	<tr>
	<td valign="top">defaultexcludes</td>
	<td valign="top">indicates whether default excludes should be used or not
	("yes"/"no"). Default excludes are used when omitted.</td>
	<td valign="top" align="center">No</td>
	</tr>
	<tr>
	<td valign="top">update</td>
	<td valign="top">indicates whether to update or overwrite
	the destination file if it already exists. Default is "false".</td>
	<td valign="top" align="center">No</td>
	</tr>
	<tr>
	<td valign="top">whenempty</td>
	<td valign="top">behavior when no files match. Valid values are "fail", "skip", and "create". Default is "skip".</td>
	<td valign="top" align="center">No</td>
	</tr>
	<tr>
	<td valign="top">duplicate</td>
	<td valign="top">behavior when a duplicate file is found. Valid values are "add", "preserve", and "fail". The default value is "add". </td>
	<td valign="top" align="center">No</td>
	</tr>
	</table>
	<h3>Parameters specified as nested elements</h3>
	<h4>fileset</h4>
	<p>The zip task supports any number of nested <a
	href="../CoreTypes/fileset.html"><code><fileset></code></a> elements to specify
	the files to be included in the archive.</p>

	<h4>zipfileset</h4>

	<p>The zip task supports any number of nested <a
	href="../CoreTypes/zipfileset.html"><code><zipfileset></code></a> elements to specify
	the files to be included in the archive.</p>

	<h4>zipgroupfileset</h4>
	<p>A <code><zipgroupfileset></code> allows for multiple zip files to be
	merged into the archive. Each file found in this fileset is added to the archive
	the same way that <i>zipfileset src</i> files are added.</p>


	<h3>Examples</h3>
	<pre> <zip destfile="${dist}/manual.zip"
	basedir="htdocs/manual"
	/></pre>
	<p>zips all files in the <code>htdocs/manual</code> directory into a file called <code>manual.zip</code>
	in the <code>${dist}</code> directory.</p>
	<pre> <zip destfile="${dist}/manual.zip"
	basedir="htdocs/manual"
	update="true"
	/></pre>
	<p>zips all files in the <code>htdocs/manual</code> directory into a file called <code>manual.zip</code>
	in the <code>${dist}</code> directory. If <code>manual.zip</code>
	doesn't exist, it is created; otherwise it is updated with the
	new/changed files.</p>
	<pre> <zip destfile="${dist}/manual.zip"
	basedir="htdocs/manual"
	excludes="mydocs/, /todo.html"
	/></pre>
	<p>zips all files in the <code>htdocs/manual</code> directory. Files in the directory <code>mydocs</code>,
	or files with the name <code>todo.html</code> are excluded.</p>
	<pre> <zip destfile="${dist}/manual.zip"
	basedir="htdocs/manual"
	includes="api/*/.html"
	excludes="**/todo.html"
	/></pre>
	<p>zips all files in the <code>htdocs/manual</code> directory. Only html files under the directory <code>api</code>
	are zipped, and files with the name <code>todo.html</code> are excluded.</p>
	<pre> <zip destfile="${dist}/manual.zip">
	<fileset dir="htdocs/manual"/>
	<fileset dir="." includes="ChangeLog.txt"/>
	</zip></pre>
	<p>zips all files in the <code>htdocs/manual</code> directory, and also adds the file <code>ChangeLog.txt</code> in the
	current directory. <code>ChangeLog.txt</code> will be added to the top of the ZIP file, just as if
	it had been located at <code>htdocs/manual/ChangeLog.txt</code>.</p>
	<pre> <zip destfile="${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></pre>
	<p>zips all files in the <code>htdocs/manual</code> directory into the <code>docs/user-guide</code> directory
	in the archive, adds the file <code>ChangeLog27.txt</code> in the
	current directory as <code>docs/ChangeLog.txt</code>, and includes all the html files in <code>examples.zip</code>
	under <code>docs/examples</code>. The archive might end up containing the files:</p>
	<pre><code> docs/user-guide/html/index.html
	docs/ChangeLog.txt
	docs/examples/index.html
	</code></pre>
	<p>
	The code
	<pre>
	<zip destfile="${dist}/manual.zip">
	<zipfileset dir="htdocs/manual" prefix="docs/user-guide"/>
	<zipgroupfileset dir="." includes="examples*.zip"/>
	</zip></pre>
	</pre>
	<p>
	<p>zips all files in the <code>htdocs/manual</code> directory into the <code>docs/user-guide</code> directory in the archive and includes all the files in any file that maches <code>examples*.zip</code>, such as all files within <code>examples1.zip</code> or <code>examples_for_brian.zip</code>.
	<hr>
	<p align="center">Copyright © 2000-2003 Apache Software Foundation. All rights
	Reserved.</p>

	</body>
	</html>