Ant 目录和文件相关的任务

基于目录的任务

某些任务使用目录树执行操作。例如，javac 任务就是这些基于目录的任务之一，它将包含 .java 文件的目录树编译成 .class 文件。由于其中一些任务对目录树做了大量工作，因此任务本身可以充当隐式文件集。

无论文件集是隐式的还是非隐式的，处理目录树的子集通常非常有用。Apache Ant 提供了两种在文件集中创建文件子集的方法，这两种方法都可以同时使用：

• 仅包含匹配任何 include 模式但不匹配任何 exclude 模式的文件和目录。请参考模式集。
• 根据选择器的嵌套元素集合所定义的选择条件来选择文件。请参考选择器。

基于文件的任务

Mkdir

Mkdir Task 创建一个目录。必要时还将创建不存在的父目录。如果目录已存在，则不执行任何操作。

参数

Attribute	Description	Required
dir	要创建的目录。	Yes

示例

创建一个目录。

创建目录 ${dist}/lib。

Filter

Filter Task 为此项目设置 token 过滤器，或将属性文件读取为多个 token 过滤器定义并进行设置。token 过滤器由通过项目方法执行文件复制操作的所有 Task 使用。使用前请参阅此处的警告。

Task 使用 @ 作为 token 分隔符。token 字符串不能包含分隔符；不正确的 token 将被忽略。

参数

Attribute	Description	Required
token	不含分隔符（@）的 token 字符串。	Yes；token 加 value 的组合，或者单个 filtersfile 二选一
value	当复制文件时要需要替换 token 的字符串。	Yes；token 加 value 的组合，或者单个 filtersfile 二选一
filtersfile	含有所需过滤器的文件路径，该文件必须是一个 property 文件。	Yes；token 加 value 的组合，或者单个 filtersfile 二选一

示例

将 src.dir 目录中的所有文件递归复制到 dest.dir 目录中，将所有出现的字符串 @year@ 替换为 2000。

从 deploy_env.properties 文件中读取所有 property 条目，并将其设置为过滤器。

Copy

Copy Task 将文件或资源集合复制到新文件或目录。默认情况下，仅当源文件比目标文件新或目标文件不存在时，才会复制文件。但是，可以使用 overwrite attribute 显式覆盖文件。资源集合用于选择要复制的一组文件。要使用资源集合，必须设置 todir attribute。请注意，某些资源（例如文件资源）以名称的形式返回绝对路径，并且在不使用嵌套映射器（或 flatten 属性）的情况下使用它们的结果可能不是您所期望的结果。

注意：如果在复制操作中使用过滤器，则应将复制操作仅限于文本文件，带过滤器的复制操作可能会损坏二进制文件。无论过滤器是由 filter Task 隐式定义的，还是作为 filterset 显式提供给复制操作，这都适用。参见编码注释。

参数

Attribute	Description	Required
file	要复制的源文件。	Yes，除非使用了内嵌的资源集合。
preservelastmodified	为复制后的目标文件指定与原始源文件相同的上次修改时间。	No；默认为 false。
tofile	复制的目标文件位置。在 Ant 1.8.2 之前，该 attribute 仅支持文件资源的复制。	通过 file attribute，可以使用 tofile 或 todir。对于嵌套的资源集合元素，如果包含的资源数大于 1，或者如果在 中仅指定了 dir attribute，或者如果还指定了 file attribute，则只允许 todir。
todir	复制的目标目录位置。
overwrite	是否覆盖已经存在的目标文件，即使目标文件的时间更新。	No；默认为 false。
force	是否覆盖只读的目标文件。自 Ant 1.8.2 开始引入。	No；默认为 false。
filtering	指示是否应在复制期间使用全局的构建文件过滤器进行 token 过滤。注意：将始终使用嵌套的 元素（即使未指定该 attribute），或其值为 false、no 或 off。	No；默认为 false。
flatten	忽略源文件的目录结构，并将所有文件复制到 todir attribute 指定的目录中。请注意，使用 flatten mapper 可以实现相同的效果。	No；默认为 false。
includeEmptyDirs	是否复制文件集中包含的所有空目录。	No；默认为 true。
failonerror	如果为 false，则在要复制的文件不存在、或其中一个嵌套文件集指向不存在的目录、或复制时发生错误时，记录警告消息，但不要停止生成。	No；默认为 true。
quiet	如果该 attribute 为 true，failonerror 为 false，则当要复制的文件不存在、或其中一个嵌套文件集指向不存在的目录、或复制时发生错误时，不要记录警告消息。从 Ant 1.8.3 开始。	No；默认为 false。
verbose	打印出正在复制的文件路径。	No；默认为 false。
encoding	过滤器复制文件时采用的编码。从 Ant 1.5 开始。	No；默认为默认的 JVM 字符编码。
outputencoding	写入文件时要使用的编码。从 Ant 1.6 开始。	No；默认为设置的编码，如果没有设置则为默认的 JVM 编码。
enablemultiplemappings	如果该 attribute 为 true，Task 将处理给定源路径的所有映射。如果该 attribute 为 false，则该 Task 将仅处理第一个文件或目录。仅当存在 子元素时，该 attribute 才相关。从 Ant 1.6 开始。	No；默认为 false。
granularity	在确定文件已过期之前，可以留出的毫秒数。这是必需的，因为不是每个文件系统都支持将上次修改的时间跟踪到毫秒级。如果源文件和目标文件位于不同的计算机上，并且时钟不同步，那么这也很有用。从 Ant 1.6.2 开始。	No；默认为 1 秒，DOS 系统默认为 两秒。

指定为嵌套元素的参数

• 任意基于文件系统的资源集合。资源集合用于选择要复制的文件组。要使用资源集合，必须设置 todir attribute。在 Ant 1.7 之前，只有 被支持作为嵌套元素。
• mapper。可以使用嵌套的 元素定义文件名转换。Copy Task 所使用的默认 mapper 是 。从 Ant 1.6.3 开始，可以使用 filenamemapper 类型代替 元素。请注意，传递给映射器的源名称取决于您使用的资源集合。如果使用 或提供基准目录的任何其他集合，则传递给映射器的名称将是相对于基准目录的相对文件名。在任何其他情况下，将使用源的绝对文件名。
• filterset。过滤器集用于替换复制文件中的 token。要使用过滤器集，请使用嵌套的 元素。可以使用多个过滤器集。
• filterchain。Copy Task 支持嵌套的过滤器链。如果在同一个 Copy Task 中使用 和 元素，则首先处理所有 元素，然后处理 元素。

示例

复制单个文件。

将单个文件复制到目录。

将 src_dir 目录复制到上一级目录下的 new/dir 目录。

将一组文件复制到一个目录。

将一组文件复制到一个目录，并在文件名后面动态添加 .bak。

将一组文件复制到一个目录，在所有文件中将 @TITLE@ 文本替换为 Foo Bar。

将当前类路径设置中的所有项收集到目标目录中，使目录结构扁平化。

将某些资源复制到给定目录。

如果上面的示例没有使用 flatten 属性， 资源将返回其完整路径作为源和目标名称，并且根本不会被复制。一般来说，最好将显式映射器与使用绝对路径作为名称的资源一起使用。

使用嵌套的过滤器链将两个最新资源复制到目标目录中。

上例后面的段落也适用于本例。

在 Unix 系统中，复制文件时不保留文件权限；它们以默认的 UMASK 权限结束。这是由于缺乏在当前 Java 运行时中查询或设置文件权限的方法造成的。如果需要保留权限的复制功能，请使用

将单个文件移动到目录。

将目录移动到新目录。

或者，从 Ant 1.6.3 开始：

将一组文件移动到新目录。

将文件列表移动到新目录。

将 .bak 附加到目录中所有文件的名称。

Delete

Delete Task 删除单个文件、指定目录及其所有文件和子目录，或一个或多个资源集合指定的一组文件。 的字面含义是不包括目录，但是，当使用嵌套文件集时，可以通过将 includeEmptyDirs attribute 设置为 true 来触发删除空目录。请注意，includeEmptyDirs attribute 在任何包含目录的各种资源集合类型的上下文中都没有意义，但在任何情况下都不会尝试删除非空目录。目录是否为空取决于文件系统， include 或 exclude 模式在此处不适用。

如果您想使用该 Task 删除由编辑器创建的临时文件，似乎不会起作用，请阅读基于目录的 Task 中的默认排除集，并查看下面的 defaultexcludes attribute。

由于历史原因， 与 并不相同； 将尝试删除 x 中的所有内容，包括 x 本身，不考虑默认排除，盲目地跟随所有符号链接。如果需要更多控制，请使用嵌套的 。

参数

Attribute	Description	Required
file	指定要删除的文件，该 attribute 值可以是简单的文件名（如果该文件存在与当前 base 目录下），相对路径、或绝对路径。	file 和 dir attribute 至少二选一，除非指定了内嵌文集合。
dir	要删除目录，包含其所有文件和子目录。注意：dir attribute 不是为文件指定一个目录名，文件和目录是彼此独立的。警告：不要将该 attribute 设置为 . 和 ${basedir}，或者等价的绝对路径，除非您真的想递归删除 base 目录下的全部内容（如果当前工作目录不在 base 目录中，也会删除 base 目录本身）。	file 和 dir attribute 至少二选一，除非指定了内嵌文集合。
verbose	是否显示每个要删除的文件。	No；默认为 false。
quiet	如果指定的文件或目录不存在，则不要显示诊断消息（除非调用 Ant 时打开了 -verbose 或 -debug 开关），也不修改退出状态以反映错误。当该 attribute 设置为 true 时，如果无法删除文件或目录，则不会报告错误。此设置模拟 Unix rm 命令的 -f 选项。将该 attribute 设置为 true 意味着将 failonerror 设置为 false。	No；默认为 false。
failonerror	控制在出现错误时是停止构建，还是向屏幕报告。仅当 quiet 设置为 false 时该 attribute 才相关。	No；默认为 true。
includeemptydirs	当使用文件集时是否删除空目录。	No；默认为 false。
includes	已弃用，请使用资源集合。匹配逗号或空格分隔的路径模式列表的文件将被删除。所有文件都是相对于 dir attribute 所指定的目录。	No
includesfile	已弃用，请使用资源集合。指定一个文件名，该文件的每一行都是一个需要删除的文件路径模式。	No
excludes	已弃用，请使用资源集合。匹配逗号或空格分隔的路径模式列表的文件将不会被删除。所有文件都是相对于 dir attribute 所指定的目录。	No；默认为 defaultexcludes attribute 值，如果defaultexcludes 的值为 no，则该 attribute 的值为 none。
excludesfile	已弃用，请使用资源集合。指定一个文件名，该文件的每一行都是一个不需要删除的文件路径模式。	No
defaultexcludes	已弃用，请使用资源集合。该 attribute 表示是否使用默认排除。	No；默认为 true。
deleteonexit	表示如果删除文件失败，是否使用 File#deleteOnExit()。这将会使 JVM 在 JVM 进程终止时尝试删除文件。从 Ant 1.6.2 开始。	No；默认为 false。
removeNotFollowedSymlinks	如果符号链接未跟随时（followSymlinks attribute 为 false，或符号链接的数值过大）是否删除符号链接。从 Ant 1.8.0 开始。	No；默认为 false。
performGCOnFailedDelete	如果 Ant 删除文件或目录失败，会重试一次。如果该 attribute 设置为 true，在重试删除之前 Ant 会执行一个垃圾回收操作。将该 attribute 设置为 true 是为了解决 Windows（默认为 true）上和位于 NFS 共享存储上的目录树的一些问题。从 Ant 1.8.3 开始。	No；Windows 上默认为 true，其他操作系统上默认为 true。

示例

删除文件 /lib/ant.jar。

删除 lib 目录，包括 lib 的所有文件和子目录。

从当前目录和任何子目录中删除扩展名为 .bak 的所有文件。

删除 build 目录中的所有文件和子目录，包括 build 目录本身。

删除 build 目录中的所有文件和子目录，而不删除 build 目录本身。

删除 src 下的 Subversion 元数据目录。因为 .svn 是默认排除的开启状态，所以您必须使用 defaultexcludes 标志，否则 Ant 不会删除这些目录和其中的文件。

Get

Get Task 从 URL 获取文件。启用 verbose 选项时，该 Task 每获取 100 Kb 就输出一个 .。Java 运行时支持的任何 URL Schema 在此处都有效，包括 http:、https:、ftp: 和 jar:。

可以指定用户名和密码，在这种情况下，将使用 Basic 身份验证。这仅在 HTTPS 链接上是安全的。从 Ant 1.7.0 开始，在 Java 5 或更高版本上运行的 Ant 可以使用操作系统的代理设置（如果使用 -autoproxy 命令行选项启用）。对于早期的 Java 版本，还有 Task。启用代理后，如果请求被中继到代理，则针对本地主机的 Task 可能无法按预期工作。

参数

Attribute	Description	Required
src	要获取文件的 URL 地址。	Yes，或者一个内嵌资源集合。
dest	存储所获取文件的文件或目录位置。	Yes
verbose	输出详细的处理信息（on	off ）。	No；默认为 off
quiet	如果为 true，则仅输出错误（true	false）。	No；默认为 false
ignoreerrors	输出 error 但不当做 fatal（致命错误）。	No；默认为 false
usetimestamp	该 attribute 控制下载，以便仅在远程文件比本地副本更新时才获取远程文件。如果没有本地副本，则始终进行下载。下载文件时，下载文件的时间戳设置为远程时间戳。注意：此时间戳工具仅适用于使用 HTTP 协议的下载。	No；默认为 false
username	HTTP Basic 认证的用户名。	Yes，如果设置了 password
password	HTTP Basic 认证的密码。	Yes，如果设置了 username
maxtime	指定单次下载需要的最长时间（秒数），超过这个时间下载将会中断，当成一个错误。自 Ant 1.8.0 开始。	No；默认为 0，表示无限制
retries	设置打开 URI 的尝试次数。该 attribute 的名称具有误导性，因为值 1 表示错误时不进行重试，值 0 表示根本不访问 URI。自 Ant 1.8.0 开始。	No；默认为 3
skipexisting	跳过在本地文件系统中已存在的文件。从 Ant 1.8.0 开始。	No；默认为 false
httpusecaches	仅适用于 HTTP。如果该 attribute 设置为 true，允许在 HttpUrlConnection 级别缓存，如果该属性设置为 false，则关闭缓存。注意：这仅会提示底层的 UrlConnection 类，具体的实现和代理服务器可以自由地忽略该设置。	No；默认为 true
useragent	发送的 User-Agent HTTP 请求头。从 Ant 1.9.3 开始。	No；默认为 Ant 的版本
tryGzipEncoding	当该 attribute 设置为 true 时，Ant 会告知服务器它希望接收 gzip 编码来减少传输的数据量并透明地解压缩。将该 attribute 设置为 true 也意味着 Ant 将会自动解压 .tar.gz 及类似文件。从 Ant 1.9.5 开始。	No；默认为 false

指定为嵌套元素的参数

• 任何资源集合。资源集合用于选择要下载的 URL 组。如果集合包含多个资源，则 dest attribute 必须指向一个目录（如果存在），或者将创建一个目录（如果不存在）。除非还指定了映射器，否则目标文件名将使用源 URL 路径的最后一部分。

• mapper。可以使用嵌套 元素定义名称转换。您还可以使用任何 filenamemapper 类型来代替 元素。映射程序将接收资源的名称作为参数。将跳过映射器不返回或返回多个映射名称的任何资源。如果返回的名称是相对路径，则将其视为相对于 dest attribute。

• header。可以向请求中添加任意数量的 HTTP 头。嵌套的

  节点的 attribute 如下所示：

  Attribute	Description	Required
  name	Header 的名称。无法为 null 或空。前面和后面的空格将会移除。	Yes
  value	Header 的值。无法为 null 或空。前面和后面的空格将会移除。	Yes

示例

获取的索引页 https://ant.apache.org/，并将其存储在文件 help/index.html 中。

如果本地副本丢失或过期，则获取 Ant（当前和过去）版本管理器的 PGP 密钥。使用 verbose 选项获取进度信息。

从具有访问控制的服务器获取某些文件。虽然正在使用 HTTPS，但如果忽略它是构建文件的一部分这一事实（第三方可能读取该构建文件中的用户名和密码），那么 Basic 身份验证以明文形式发送密码是没有安全意义的。如果需要更多的安全性，请考虑使用 Input Task 来查询密码。

使用如下所示的宏，可以下载一个工件及其 SHA1 校验和（当然，假设校验和文件有某种命名约定），并动态验证校验和。

  
  
  
    
    
    
      
      
      
        
        
      
    
    
    
    
    
      
    
    Checksum error
  

获取 https://ant.apache.org/ 的索引和常见问题解答页面，并将其存储在必要时将创建的 downloads 目录中。

使用自定义 HTTP 头。

还有一些不常用的文件相关的 Task：Attrib、Checksum、Chgrp、Chmod、Chown、Patch、FixCRLF、Replace、ReplaceRegExp、SetPermissions、Concat、Sync、Tempfile、Touch。