## Move

### Description

Moves a file to a new file or directory, or collections of files to a new directory. By default, the destination file is overwritten if it already exists. When overwrite is turned off, then files are only moved if the source file is newer than the destination file, or when the destination file does not exist - please see the granularity attribute for Ant's idea of newer.

Resource collections are used to select a group of files to move. Only file system based resource collections are supported, this includes filesets, filelist and path. Prior to Apache Ant 1.7 only `<fileset>` has been supported as a nested element. To use a resource collection, the todir attribute must be set.

Since Ant 1.6.3, the file attribute may be used to move (rename) an entire directory. If tofile denotes an existing file, or there is a directory by the same name in todir, the action will fail.

### Parameters

Attribute | Description | Required
--- | --- | ---
file | the file or directory to move | One of file or at least one nested resource collection element
preservelastmodified | Give the moved 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 move to | With the file attribute, either tofile or todir can be used. With nested filesets, if the fileset size is greater than 1 or if the only entry in the fileset is a directory or if the file attribute is already specified, only todir is allowed
todir | the directory to move to
overwrite | overwrite existing files even if the destination files are newer | No; defaults to true
force | Overwrite read-only destination files. since Ant 1.8.2 | No; defaults to false
filtering | indicates whether token filtering should take place during the move. See the filter task for a description of how filters work. | No
flatten | ignore directory structure of source directory, copy all files into a single 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 empty directories included with the nested FileSet(s). | No; defaults to yes
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 moving. | 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 moved. | No; defaults to false
encoding | The encoding to assume when filter-copying the files. since Ant 1.5. | No; defaults to default JVM character encoding
outputencoding | The encoding to use when writing the files. since Ant 1.6. | No; defaults to encoding if set or default JVM character 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. This can also be useful if source and target files live on separate machines with clocks being out of sync. since Ant 1.6. | No; default is 0 milliseconds, or 2 seconds on DOS systems

performGCOnFailedDelete

If Ant fails to delete a file or directory it will retry the operation once. If this flag is set to true it will perform a garbage collection before retrying the delete.
Setting this flag to true is known to resolve some problems on Windows (where it defaults to true) but also for directory trees residing on an NFS share. Since Ant 1.8.3

No; defaults to true on Windows and false on any other OS

### Parameters specified as nested elements

#### mapper

You can define file name transformations by using a nested mapper element. The default mapper used by `<move>` is the identity.

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.

#### filterchain

The Move task supports nested FilterChains.

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

### Examples

Move a single file (rename a file)

    <move file="file.orig" tofile="file.moved"/>

Move a single file to a directory

    <move file="file.orig" todir="dir/to/move/to"/>

Move a directory to a new directory

    <move todir="new/dir/to/move/to">
      <fileset dir="src/dir"/>
    </move>

or, since Ant 1.6.3:

    <move file="src/dir" tofile="new/dir/to/move/to"/>

Move a set of files to a new directory

    <move todir="some/new/dir">
      <fileset dir="my/src/dir">
        <include name="**/*.jar"/>
        <exclude name="**/ant.jar"/>
      </fileset>
    </move>

Move a list of files to a new directory

    <move todir="some/new/dir">
      <filelist dir="my/src/dir">
        <file name="file1.txt"/>
        <file name="file2.txt"/>
      </filelist>
    </move>

Append `".bak"` to the names of all files in a directory.

    <move todir="my/src/dir" includeemptydirs="false">
      <fileset dir="my/src/dir">
        <exclude name="**/*.bak"/>
      </fileset>
      <mapper type="glob" from="*" to="*.bak"/>
    </move>