Touch Task

## Touch

### Description

Changes the modification time of a resource and possibly creates it at the same time. In addition to working with a single file, this Task can also work on resources and resource collections (which also includes directories). Prior to Apache Ant 1.7 only FileSet or Filelist (since Ant 1.6) were supported.

Ant uses the API of `java.io.File` to set the last modification time which has some limitations. For example, the timestamp granularity depends on the operating system and sometimes the operating system may allow a granularity smaller than milliseconds. If you need more control you have to fall back to the `<exec>` task and native commands.

Since Ant 1.8.2, a warning message is logged upon failure to change the file modification time. This will happen if you try to change the modification time of a file you do not own on many Unix systems, for example.

### Parameters

Attribute | Description | Required
--- | --- | ---
file | The name of the file. | Unless a nested resource collection element has been specified
millis | Specifies the new modification time of the file in milliseconds since midnight Jan 1 1970. | No; datetime takes precedence, however if both are omitted then current time is assumed
datetime | Specifies the new modification time of the file. Since Ant 1.8, the special value now indicates the current time.
pattern | SimpleDateFormat-compatible pattern string using the current locale. Since Ant 1.6.3 | No; defaults to MM/dd/YYYY hh:mm a or MM/dd/yyyy hh:mm:ss a using the US locale.
mkdirs | Whether to create nonexistent parent directories when touching new files. Since Ant 1.6.3 | No; default false
verbose | Whether to log the creation of new files. Since Ant 1.6.3 | No; default true

### Parameters specified as nested elements

#### any resource collection

You can use any number of nested resource collection elements to define the resources for this task and refer to resources defined elsewhere. Note: resources passed to this task must implement the `org.apache.tools.ant.types.resources.Touchable` interface, this is true for all filesystem-based resources like those returned by path, fileset ot filelist.

For backwards compatibility directories matched by nested filesets will be "touched" as well, use a type selector to suppress this. This only applies to filesets nested into the task directly, not to filesets nested into a path or any other resource collection.

#### mapper

Since Ant 1.6.3, a nested mapper can be specified. Files specified via nested `fileset`s, `filelist`s, or the `file` attribute are mapped using the specified mapper. For each file mapped, the resulting files are touched. If no time has been specified and the original file exists its timestamp will be used. If no time has been specified and the original file does not exist the current time is used. Since Ant 1.8, the task settings (millis and datetime) have priority over the timestamp of the original file.

### Examples

Create `myfile` if it doesn't exist and change the modification time to the current time.

    <touch file="myfile"/>

Create `myfile` if it doesn't exist and change the modification time to Jun, 28 2000 2:02 pm (14:02 for those used to 24 hour time).

    <touch file="myfile" datetime="06/28/2000 2:02 pm"/>

Change the modification time to Oct, 09 1974 4:30 pm of all files and directories found in `src_dir`.

    <touch datetime="09/10/1974 4:30 pm">
        <fileset dir="src_dir"/>
    </touch>

Create `myfile` if it doesn't exist and change the modification time to Jun, 28 2000 2:02:17 pm (14:02:17 for those used to 24 hour time), if the filesystem allows a precision of one second—a time close to it otherwise.

    <touch file="myfile" datetime="06/28/2000 2:02:17 pm"/>

Create `bar` if it doesn't exist and change the modification time to that of `foo`.

    <touch file="foo">
        <mapper type="glob" from="foo" to="bar"/>
    </touch>

Create files in the `shadow` directory for every `.java` file in the `src` directory if it doesn't exist and change the modification time of those files to the current time.

    <touch file="foo" datetime="now">
        <mapper type="regexp" from="^src(.*)\.java" to="shadow\1.empty"/>
    </touch>