| <!DOCTYPE html> |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| https://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| <html lang="en"> |
| |
| <head> |
| <link rel="stylesheet" type="text/css" href="../stylesheets/style.css"> |
| <title>Move Task</title> |
| </head> |
| |
| <body> |
| |
| <h2 id="move">Move</h2> |
| <h3>Description</h3> |
| <p>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 <var>overwrite</var> 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.</p> |
| |
| <p><a href="../Types/resources.html#collection">Resource collections</a> are used to select a group |
| of files to move. Only file system based resource collections are supported, this |
| includes <a href="../Types/fileset.html">fileset</a>s, <a href="../Types/filelist.html">filelist</a> |
| and <a href="../using.html#path">path</a>. Prior to Apache Ant 1.7 |
| only <code><fileset></code> has been supported as a nested element. To use a resource |
| collection, the <var>todir</var> attribute must be set.</p> |
| |
| <p><em>Since Ant 1.6.3</em>, the <var>file</var> attribute may be used to move (rename) an entire |
| directory. If <var>tofile</var> denotes an existing file, or there is a directory by the same name |
| in <var>todir</var>, the action will fail.</p> |
| <h3>Parameters</h3> |
| <table class="attr"> |
| <tr> |
| <th scope="col">Attribute</th> |
| <th scope="col">Description</th> |
| <th scope="col">Required</th> |
| </tr> |
| <tr> |
| <td>file</td> |
| <td>the file or directory to move</td> |
| <td>One of <var>file</var> or at least one nested resource collection element</td> |
| </tr> |
| <tr> |
| <td>preservelastmodified</td> |
| <td>Give the moved files the same last modified time as the original source files. |
| (<strong>Note</strong>: Ignored on Java 1.1)</td> |
| <td>No; defaults to <q>false</q></td> |
| </tr> |
| <tr> |
| <td>tofile</td> |
| <td>the file to move to</td> |
| <td rowspan="2">With the <var>file</var> attribute, either <var>tofile</var> or <var>todir</var> |
| 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 <var>file</var> attribute is already specified, |
| only <var>todir</var> is allowed</td> |
| </tr> |
| <tr> |
| <td>todir</td> |
| <td class="left">the directory to move to</td> |
| </tr> |
| <tr> |
| <td>overwrite</td> |
| <td>overwrite existing files even if the destination files are newer</td> |
| <td>No; defaults to <q>true</q></td> |
| </tr> |
| <tr> |
| <td>force</td> |
| <td>Overwrite read-only destination files. <em>since Ant 1.8.2</em></td> |
| <td>No; defaults to <q>false</q></td> |
| </tr> |
| <tr> |
| <td>filtering</td> |
| <td>indicates whether token filtering should take place during the move. See |
| the <a href="filter.html">filter</a> task for a description of how filters work.</td> |
| <td>No</td> |
| </tr> |
| <tr> |
| <td>flatten</td> |
| <td>ignore directory structure of source directory, copy all files into a single directory, |
| specified by the <var>todir</var> attribute. Note that you can achieve the same effect by |
| using a <a href="../Types/mapper.html#flatten-mapper">flatten mapper</a></td> |
| <td>No; defaults to <q>false</q></td> |
| </tr> |
| <tr> |
| <td>includeEmptyDirs</td> |
| <td>Copy empty directories included with the nested FileSet(s).</td> |
| <td>No; defaults to <q>yes</q></td> |
| </tr> |
| <tr> |
| <td>failonerror</td> |
| <td>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.</td> |
| <td>No; defaults to <q>true</q></td> |
| </tr> |
| <tr> |
| <td>quiet</td> |
| <td>If <q>true</q> and <var>failonerror</var> is <q>false</q>, 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. <em>since Ant 1.8.3</em>.</td> |
| <td>No; defaults to <q>false</q></td> |
| </tr> |
| <tr> |
| <td>verbose</td> |
| <td>Log the files that are being moved.</td> |
| <td>No; defaults to <q>false</q></td> |
| </tr> |
| <tr> |
| <td>encoding</td> |
| <td>The encoding to assume when filter-copying the files. <em>since Ant 1.5</em>.</td> |
| <td>No; defaults to default JVM character encoding</td> |
| </tr> |
| <tr> |
| <td>outputencoding</td> |
| <td>The encoding to use when writing the files. <em>since Ant 1.6</em>.</td> |
| <td>No; defaults to <var>encoding</var> if set or default JVM character encoding otherwise</td> |
| </tr> |
| <tr> |
| <td>enablemultiplemappings</td> |
| <td>If <q>true</q> the task will process to all the mappings for a given source |
| path. If <q>false</q> the task will only process the first file or directory. This attribute |
| is only relevant if there is a <code>mapper</code> subelement. <em>since Ant 1.6</em>.</td> |
| <td>No; defaults to <q>false</q></td> |
| </tr> |
| <tr> |
| <td>granularity</td> |
| <td>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. <em>since Ant 1.6</em>.</td> |
| <td>No; default is 0 milliseconds, or 2 seconds on DOS systems</td> |
| </tr> |
| <tr> |
| <td>performGCOnFailedDelete</td> |
| <td>If Ant fails to delete a file or directory it will retry the operation once. If this flag |
| is set to <q>true</q> it will perform a garbage collection before retrying the delete.<br/> |
| Setting this flag to <q>true</q> is known to resolve some problems on Windows (where it |
| defaults to <q>true</q>) but also for directory trees residing on an NFS share. <em>Since Ant |
| 1.8.3</em></td> |
| <td>No; defaults to <q>true</q> on Windows and <q>false</q> on any other OS</td> |
| </tr> |
| </table> |
| <h3>Parameters specified as nested elements</h3> |
| <h4>mapper</h4> |
| <p>You can define file name transformations by using a |
| nested <a href="../Types/mapper.html">mapper</a> element. The default mapper used |
| by <code><move></code> is the <a href="../Types/mapper.html#identity-mapper">identity</a>.</p> |
| <p>Note that the source name handed to the mapper depends on the resource collection you use. If |
| you use <code><fileset></code> 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.</p> |
| <h4>filterchain</h4> |
| <p>The Move task supports nested <a href="../Types/filterchain.html">FilterChain</a>s.</p> |
| <p>If <code><filterset></code> and <code><filterchain></code> elements are used inside |
| the same <code><move></code> task, all <code><filterchain></code> elements are processed |
| first followed by <code><filterset></code> elements.</p> |
| |
| <h3>Examples</h3> |
| <p>Move a single file (rename a file)</p> |
| <pre><move file="file.orig" tofile="file.moved"/></pre> |
| |
| <p>Move a single file to a directory</p> |
| <pre><move file="file.orig" todir="dir/to/move/to"/></pre> |
| |
| <p>Move a directory to a new directory</p> |
| <pre> |
| <move todir="new/dir/to/move/to"> |
| <fileset dir="src/dir"/> |
| </move></pre> |
| <p>or, <em>since Ant 1.6.3</em>:</p> |
| <pre><move file="src/dir" tofile="new/dir/to/move/to"/></pre> |
| |
| <p>Move a set of files to a new directory</p> |
| <pre> |
| <move todir="some/new/dir"> |
| <fileset dir="my/src/dir"> |
| <include name="**/*.jar"/> |
| <exclude name="**/ant.jar"/> |
| </fileset> |
| </move></pre> |
| |
| <p>Move a list of files to a new directory</p> |
| <pre> |
| <move todir="some/new/dir"> |
| <filelist dir="my/src/dir"> |
| <file name="file1.txt"/> |
| <file name="file2.txt"/> |
| </filelist> |
| </move></pre> |
| |
| <p>Append <code>".bak"</code> to the names of all files in a directory.</p> |
| <pre> |
| <move todir="my/src/dir" includeemptydirs="false"> |
| <fileset dir="my/src/dir"> |
| <exclude name="**/*.bak"/> |
| </fileset> |
| <mapper type="glob" from="*" to="*.bak"/> |
| </move></pre> |
| |
| </body> |
| </html> |