youys
/
ant

<html>

<head>
<meta http-equiv="Content-Language" content="en-us">
<title>Copy Task</title>
</head>

<body>

<h2><a name="copy">Copy</a></h2>
<h3>Description</h3>
<p>Copies a file or FileSet to a new file or directory.  By default, files are
only copied if the source file is newer than the destination file,
or when the destination file does not exist.  However, you can explicitly
overwrite files with the <code>overwrite</code> attribute.</p>
<p><a href="../CoreTypes/fileset.html">FileSet</a>s are used to select a
set of files to copy.
To use a <code>&lt;fileset&gt;</code>, the <code>todir</code> attribute
must be set.</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 align="center" valign="top"><b>Required</b></td>
  </tr>
  <tr>
    <td valign="top">file</td>
    <td valign="top">The file to copy.</td>
    <td valign="top" align="center">Yes, unless a nested
    <code>&lt;fileset&gt;</code> element is used.</td>
  </tr>
  <tr>
    <td valign="top">preservelastmodified</td>
    <td valign="top">Give the copied files the same last modified
      time as the original source files.
      (<em>Note</em>: Ignored on Java 1.1)</td>
    <td valign="top" align="center">No; defaults to false.</td>
  </tr>
  <tr>
    <td valign="top">tofile</td>
    <td valign="top">The file to copy to.</td>
    <td valign="top" align="center" rowspan="2">With the <code>file</code>
      attribute, either <code>tofile</code> or <code>todir</code> can be used.
      With nested <code>&lt;fileset&gt;</code> elements, if the set of files
      is greater than 1, or if only the <code>dir</code> attribute is
      specified in the <code>&lt;fileset&gt;</code>, or if the
      <code>file</code> attribute is also specified, then only
      <code>todir</code> is allowed.</td>
  </tr>
  <tr>
    <td valign="top">todir</td>
    <td valign="top">The directory to copy to.</td>
  </tr>
  <tr>
    <td valign="top">overwrite</td>
    <td valign="top">Overwrite existing files even if the destination
      files are newer.</td>
    <td valign="top" align="center">No; defaults to false.</td>
  </tr>
  <tr>
    <td valign="top">filtering</td>
    <td valign="top">Indicates whether token filtering using the global
      build-file filters should take place during the copy.
      <em>Note</em>: Nested <code>&lt;filterset&gt;</code> elements will
      always be used, even if this attribute is not specified, or its value is
      <code>false</code> (<code>no</code>, or <code>off</code>).</td>
    <td valign="top" align="center">No; defaults to false.</td>
  </tr>
  <tr>
    <td valign="top">flatten</td>
    <td valign="top">Ignore the directory structure of the source files,
      and copy all files into the directory specified by the <code>todir</code>
      attribute.  Note that you can achieve the same effect by using a
      <a href="../CoreTypes/mapper.html#flatten-mapper">flatten mapper</a>.</td>
    <td valign="top" align="center">No; defaults to false.</td>
  </tr>
  <tr>
    <td valign="top">includeEmptyDirs</td>
     <td valign="top">Copy any empty directories included in the FileSet(s).
     </td>
     <td valign="top" align="center">No; defaults to true.</td>
  </tr>
  <tr>
    <td valign="top">failonerror</td>
     <td valign="top">Log a warning message, but do not stop the build,
       when the file to copy does not exist.
       Only meaningful when copying a single file.
     </td>
     <td valign="top" align="center">No; defaults to true.</td>
  </tr>
  <tr>
    <td valign="top">verbose</td>
     <td valign="top">Log the files that are being copied.</td>
     <td valign="top" align="center">No; defaults to false.</td>
  </tr>
</table>
<h3>Parameters specified as nested elements</h3>

<h4>fileset</h4>
 <p><a href="../CoreTypes/fileset.html">FileSet</a>s are used to select
sets of files to copy.
 To use a fileset, the <code>todir</code> attribute must be set.</p>

<h4>mapper</h4>
 <p>You can define filename transformations by using a nested <a
 href="../CoreTypes/mapper.html">mapper</a> element. The default mapper used by
 <code>&lt;copy&gt;</code> is the <a
 href="../CoreTypes/mapper.html#identity-mapper">identity mapper</a>.</p>

<h4>filterset</h4>
 <p><a href="../CoreTypes/filterset.html">FilterSet</a>s are used to replace
tokens in files that are copied.
 To use a FilterSet, use the nested <code>&lt;filterset&gt;</code> element.</p>

<h4>filterchain</h4>
<p>The Copy task supports nested <a href="../CoreTypes/filterchain.html">
FilterChain</a>s.</p>

<p>
If &lt;filterset&gt; and &lt;filterchain&gt; elements are used inside the
same &lt;copy&gt; task, all &lt;filterchain&gt; elements are processed first
followed by &lt;filterset&gt; elements.
</p>

<h3>Examples</h3>
<p><b>Copy a single file</b></p>
<pre>
  &lt;copy file=&quot;myfile.txt&quot; tofile=&quot;mycopy.txt&quot;/&gt;
</pre>
<p><b>Copy a single file to a directory</b></p>
<pre>
  &lt;copy file=&quot;myfile.txt&quot; todir=&quot;../some/other/dir&quot;/&gt;
</pre>
<p><b>Copy a directory to another directory</b></p>
<pre>
  &lt;copy todir=&quot;../new/dir&quot;&gt;
    &lt;fileset dir=&quot;src_dir&quot;/&gt;
  &lt;/copy&gt;
</pre>
<p><b>Copy a set of files to a directory</b></p>
<pre>
  &lt;copy todir=&quot;../dest/dir&quot; &gt;
    &lt;fileset dir=&quot;src_dir&quot; &gt;
      &lt;exclude name=&quot;**/*.java&quot;/&gt;
    &lt;/fileset&gt;
  &lt;/copy&gt;

  &lt;copy todir=&quot;../dest/dir&quot; &gt;
    &lt;fileset dir=&quot;src_dir&quot; excludes=&quot;**/*.java&quot;/&gt;
  &lt;/copy&gt;
</pre>
<p><b>Copy a set of files to a directory, appending
<code>.bak</code> to the file name on the fly</b></p>
<pre>
  &lt;copy todir=&quot;../backup/dir&quot; &gt;
    &lt;fileset dir=&quot;src_dir&quot; /&gt;
    &lt;mapper type=&quot;glob&quot; from=&quot;*&quot; to=&quot;*.bak&quot;/&gt;
  &lt;/copy&gt;
</pre>


<p><b>Copy a set of files to a directory, replacing @TITLE@ with Foo Bar
in all files.</b></p>
<pre>
  &lt;copy todir=&quot;../backup/dir&quot; &gt;
    &lt;fileset dir=&quot;src_dir&quot; /&gt;
    &lt;filterset&gt;
      &lt;filter token=&quot;TITLE&quot; value=&quot;Foo Bar&quot; /&gt;
    &lt;/filterset&gt;
  &lt;/copy&gt;
</pre>

<p><strong>Unix Note:</strong> File permissions are not retained when files
are copied; they end up with the default <code>UMASK</code> permissions
instead. This
is caused by the lack of any means to query or set file permissions in the
current Java runtimes. If you need a permission-preserving copy function,
use <code>&lt;exec executable="cp" ... &gt;</code> instead.
</p>

<p><strong>Windows Note:</strong> If you copy a file to a directory
where that file already exists, but with different casing,
the copied file takes on the case of the original. The workaround is to
<a href="delete.html">delete</a>
the file in the destination directory before you copy it.
</p>

<hr><p align="center">Copyright &copy; 2000-2002 Apache Software Foundation.
All rights Reserved.</p>

</body>
</html>