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
FileSets are used to select a
set of files to copy.
To use a
must be set.
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
|file||The file to copy.||Yes, unless a nested
|preservelastmodified||Give the copied files the same last modified time as the original source files. (Note: Ignored on Java 1.1)||No; defaults to false.|
|tofile||The file to copy to.||With the
|todir||The directory to copy to.|
|overwrite||Overwrite existing files even if the destination files are newer.||No; defaults to false.|
|filtering||Indicates whether token filtering using the global
build-file filters should take place during the copy.
||No; defaults to false.|
|flatten||Ignore the directory structure of the source files,
and copy all files into the directory specified by the
||No; defaults to false.|
|includeEmptyDirs||Copy any empty directories included in the FileSet(s).||No; defaults to true.|
|failonerror||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.|
|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.|
FileSets are used to select
sets of files to copy.
To use a fileset, the
todir attribute must be set.
You can define filename transformations by using a nested mapper element. The default mapper used by
<copy> is the identity mapper.
FilterSets are used to replace
tokens in files that are copied.
To use a FilterSet, use the nested
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.
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"/> <mapper type="glob" 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>
Unix Note: File permissions are not retained when files
are copied; they end up with the default
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,
<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.
Copyright © 2000-2004 The Apache Software Foundation. All rights Reserved.