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

Attribute

Description

Required

file

The file to copy.

Yes, unless a nested
resource collection element is used.

preservelastmodified

Give the copied files the same last modified
time as the original source files.

No; defaults to false.

tofile

The file to copy to.

With the file
attribute, either tofile or todir can be used.
With nested resource collection elements, if the number of
included resources
is greater than 1, or if only the dir attribute is
specified in the <fileset>, or if the
file attribute is also specified, then only
todir is allowed.Prior to Apache Ant 1.8.2 the tofile attribute
only supported filesystem resources top copy from.

todir

The directory to copy to.

overwrite

Overwrite existing files even if the destination
files are newer.

No; defaults to false.

force

Overwrite read-only destination
files. since Ant 1.8.2

No; defaults to false.

filtering

Indicates whether token filtering using the global
build-file filters should take place during the copy.
Note: Nested <filterset> elements will
always be used, even if this attribute is not specified, or its value is
false (no, or off).

No; defaults to false.

flatten

Ignore the directory structure of the source files,
and copy all files into the directory specified by the todir
attribute. Note that you can achieve the same effect by using a
flatten mapper.

No; defaults to false.

includeEmptyDirs

Copy any empty directories included in the FileSet(s).

No; defaults to true.

failonerror

If false, log a warning message, but do not stop the
build, when the file to copy does not exist or one of the nested
filesets points to a directory that doesn't exist or an error occurs
while copying.

No; defaults to true.

quiet

If true and failonerror is false, then do not log a
warning message when the file to copy does not exist or one of the nested
filesets points to a directory that doesn't exist or an error occurs
while copying. since Ant 1.8.3.

No; defaults to false.

verbose

Log the files that are being copied.

No; defaults to false.

encoding

The encoding to assume when filter-copying the
files. since Ant 1.5.

No - defaults to default JVM encoding

outputencoding

The encoding to use when writing the files.
since Ant 1.6.

No - defaults to the value of the encoding
attribute if given or the default JVM encoding otherwise.

enablemultiplemappings

If true the task will process to all the mappings for a
given source path. If false the task will only process
the first file or directory. This attribute is only relevant
if there is a mapper subelement.
since Ant 1.6.

No - defaults to false.

granularity

The number of milliseconds leeway to give before
deciding a file is out of date. This is needed because not every
file system supports tracking the last modified time to the
millisecond level. Default is 1 second, or 2 seconds on DOS
systems. This can also be useful if source and target files live
on separate machines with clocks being out of sync. since Ant
1.6.2.

No

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.

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.

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 specifying 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 implementation is to
map them to legal characters. Previous Sun Java (1.3 and lower) threw
a MalformedInputException. IBM Java 1.4 also throws 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".