Copy

Description

Copies a file or resource collection 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 overwrite attribute.

Resource Collections are used to select a group of files to copy. To use a resource collection, the todir attribute must be set. Note that some resources (for example the file resource) return absolute paths as names and the result of using them without using a nested mapper (or the flatten attribute) may not be what you expect.

Note: If you employ filters in your copy operation, you should limit the copy to text files. Binary files will be corrupted by the copy operation. This applies whether the filters are implicitly defined by the filter task or explicitly provided to the copy operation as filtersets. See encoding note.

Parameters

Parameters specified as nested elements

fileset or any other resource collection

Resource Collections are used to select groups of files to copy. To use a resource collection, the todir attribute must be set.

Prior to Ant 1.7 only <fileset> has been supported as a nested element.

mapper

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

Since Ant 1.6.3, one can use a filenamemapper type in place of the mapper element.

Note that the source name handed to the mapper depends on the resource collection you use. If you use <fileset> or any other collection that provides a base directory, the name passed to the mapper will be a relative filename, relative to the base directory. In any other case the absolute filename of the source will be used.

filterset

FilterSets are used to replace tokens in files that are copied. To use a FilterSet, use the nested <filterset> element.

It is possible to use more than one filterset.

filterchain

The Copy task supports nested FilterChains.

If <filterset> and <filterchain> elements are used inside the same <copy> task, all <filterchain> elements are processed first followed by <filterset> elements.

Examples

Copy a single file

  <copy file="myfile.txt" tofile="mycopy.txt"/>

Copy a single file to a directory

  <copy file="myfile.txt" todir="../some/other/dir"/>

Copy a directory to another directory

  <copy todir="../new/dir">
    <fileset dir="src_dir"/>
  </copy>

Copy a set of files to a directory

  <copy todir="../dest/dir">
    <fileset dir="src_dir">
      <exclude name="**/*.java"/>
    </fileset>
  </copy>

  <copy todir="../dest/dir">
    <fileset dir="src_dir" excludes="**/*.java"/>
  </copy>

Copy a set of files to a directory, appending .bak to the file name on the fly

  <copy todir="../backup/dir">
    <fileset dir="src_dir"/>
    <globmapper from="*" to="*.bak"/>
  </copy>

Copy a set of files to a directory, replacing @TITLE@ with Foo Bar in all files.

  <copy todir="../backup/dir">
    <fileset dir="src_dir"/>
    <filterset>
      <filter token="TITLE" value="Foo Bar"/>
    </filterset>
  </copy>

Collect all items from the current CLASSPATH setting into a destination directory, flattening the directory structure.

  <copy todir="dest" flatten="true">
    <path>
      <pathelement path="${java.class.path}"/>
    </path>
  </copy>

Copies some resources to a given directory.

  <copy todir="dest" flatten="true">
    <resources>
      <file file="src_dir/file1.txt"/>
      <url url="http://ant.apache.org/index.html"/>
    </resources>
  </copy>

If the example above didn't use the flatten attribute, the <file> resource would have returned its full path as source and target name and would not have been copied at all. In general it is a good practice to use an explicit mapper together with resources that use an absolute path as their names.

Copies the two newest resources into a destination directory.

  <copy todir="dest" flatten="true">
    <first count="2">
      <sort>
        <date xmlns="antlib:org.apache.tools.ant.types.resources.comparators"/>
        <resources>
          <file file="src_dir/file1.txt"/>
          <file file="src_dir/file2.txt"/>
          <file file="src_dir/file3.txt"/>
          <url url="http://ant.apache.org/index.html"/>
        </resources>
      </sort>
    </first>
  </copy>

The paragraph following the previous example applies to this example as well.

Unix Note: File permissions are not retained when files are copied; they end up with the default UMASK 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 <exec executable="cp" ... > instead.

Windows Note: 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 delete the file in the destination directory before you copy it.

Important Encoding Note: The reason that binary files when filtered get corrupted is that filtering involves reading in the file using a Reader class. This has an encoding specifing how files are encoded. There are a number of different types of encoding - UTF-8, UTF-16, Cp1252, ISO-8859-1, US-ASCII and (lots) others. On Windows the default character encoding is Cp1252, on Unix it is usually UTF-8. For both of these encoding there are illegal byte sequences (more in UTF-8 than for Cp1252).

How the Reader class deals with these illegal sequences is up to the implementation of the character decoder. The current Sun Java implemenation is to map them to legal characters. Previous Sun Java (1.3 and lower) threw a MalformedInputException. IBM Java 1.4 also thows this exception. It is the mapping of the characters that cause the corruption.

On Unix, where the default is normally UTF-8, this is a big problem, as it is easy to edit a file to contain non US Ascii characters from ISO-8859-1, for example the Danish oe character. When this is copied (with filtering) by Ant, the character get converted to a question mark (or some such thing).

There is not much that Ant can do. It cannot figure out which files are binary - a UTF-8 version of Korean will have lots of bytes with the top bit set. It is not informed about illegal character sequences by current Sun Java implementions.

One trick for filtering containing only US-ASCII is to use the ISO-8859-1 encoding. This does not seem to contain illegal character sequences, and the lower 7 bits are US-ASCII. Another trick is to change the LANG environment variable from something like "us.utf8" to "us".