Description

Copy a file or fileset to a new file or directory. Files are only copied if the source file is newer than the destination file, or when the destination file does not exist.

Parameters

file

Description: File to be copied

Domain: Valid filename pointing to existing file

Default: -

to_file

Description: File to copy to

Domain: Valid filename

Default: -

to_directory

Description: Directory to which file(s) should be copied to

Domain: Valid directoryname pointing to existing directory

Default: -

force

Description: Copy file even when the possibly existing target file is not out of date.

Domain: Boolean (true|false)

Default: false

RNG Specification

  <define name="copy">
    <element name="copy">
      <ref name="dir_if_unless"/>
        <choice>
          <group>
            <attribute name="file"/>
            <attribute name="to_file"/>
          </group>
          <group>
            <attribute name="file"/>
            <attribute name="to_directory"/>
          </group>
          <group>
            <attribute name="to_directory"/>
            <ref name="fileset"/>
          </group>
        </choice>
      <optional>
        <attribute name="force">
          <!-- runtime evaluation
          <choice>
            <value>true</value>
            <value>false</value>
          </choice>
          -->
        </attribute>
      </optional>
    </element>
  </define>

	

Examples

Copy a single file:

  <copy file="readme.txt" to_file="readme1.txt"/>

Copy a single file to a directory:

  <copy file="readme.txt" to_directory="/tmp"/>

Copy a single file even if this would not be necessary:

By default the copy task only copies files if the target file is out of date. With the force flag set to true it is always copied.

  <copy file="readme.txt" to_directory="/tmp" force="true"/>

Copy a directory to another directory:

Let's assume we have the directories 'input' and 'output' under the current directory. If we want to copy the directory 'input' to directory 'output' do it as follows:

  <copy to_directory="output">
    <fileset include="@(input/**/*)"/>
  </copy>

Copy a directory to another directory

Let's assume we have the directories 'input', 'input/1' and 'output' under the current directory. What we want is to copy the directory '1' in directory 'input' to directory 'output'. There are a couple of ways to achieve this from which three are shown here:

Possibility 1 (probably the easiest way):

    <copy to_directory="../output" dir="input">
      <fileset include="@(1/**/*)"/>
    </copy>

Possibility 2:

  <copy to_directory="output">
    <fileset include="@(1/**/*)" filename_directory="input" dir="input"/>
  </copy>

Possibility 3:

  <copy to_directory="output">
    <fileset include="@(input/1/**/*)">
      <map type="glob" from="input/*" to="*"/>
    </fileset>
  </copy>

Description for possibility 1:

The 'copy' task is executed from within the directory 'input'. Therefore the attribute 'to_directory' has to be set to '../output'.

Description for possibility 2:

In a first attempt we might use this approach:

  <copy to_directory="output">
    <fileset include="@(input/1/**/*)"/>
  </copy>

But with this approach we end up with the directory 'output/input/1/...' which is not what we want. We need to get rid of the input in the selected filenames. To achieve this we set the attribute 'dir' of the fileset to the directory 'input' so that for the time the fileset executes it is collecting the appropriate filenames from within the directory 'input':

  <copy to_directory="output">
    <fileset include="@(1/**/*)" dir="input"/>
  </copy>

Now the fileset contains the filenames we want. Unfortunately the 'copy' task cannot work with them since it cannot copy files from '1/**' because they are in the directory 'input'. So what we need is that 'input' is prepended anyway but only to read the files while copying and not for writing. To achieve this we set the attribute 'filename_directory' to 'input'. The value of this attribute ('input' in this case) will be prepended to the source name while the target name remains as is. For example for a matched filename '1/somedir/readme.txt' the source filename will become 'input/1/somedir/readme.txt' but the target filename will still be '1/somedir/readme.txt'. So our working 'copy' task is:

  <copy to_directory="output">
    <fileset include="@(1/**/*)" filename_directory="input" dir="input"/>
  </copy>

Description for possibility 3:

If we start again go back to our first attempt from possibility 2 which produces the undesired 'input' directory:

  <copy to_directory="output">
    <fileset include="@(input/1/**/*)"/>
  </copy>

... it is more natural to come to the conclusion that all that needs to be done is removing that 'input/' from the target filenames. The element 'fileset' provides an attribute called 'mapped_filename_directory' but that is only for prepending and not for removal. But using a nested map does the trick:

  <copy to_directory="output">
    <fileset include="@(input/1/**/*)">
      <map type="glob" from="input/*" to="*"/>
    </fileset>
  </copy>