TStamp Task

## Tstamp

### Description

Sets the `DSTAMP`, `TSTAMP`, and `TODAY` properties in the current project. By default, the `DSTAMP` property is in the format yyyyMMdd, `TSTAMP` is in the format HHmm, and `TODAY` is in the format MMMM d yyyy. Use the nested `<format>` element to specify a different format.

These properties can be used in the build file, for instance, to create timestamped filenames, or used to replace placeholder tags inside documents to indicate, for example, the release date. The best place for this task is probably in an initialization target.

Since Ant 1.10.2 the magic property `ant.tstamp.now` can be used to specify a fixed date value in order to create reproducible builds. Its value must be a number and is interpreted as seconds since the epoch (midnight 1970-01-01). With `ant.tstamp.now.iso` you could also specify that value in ISO-8601 format (`1972-04-17T08:07:00Z`). If you specify a value in an invalid format an INFO message will be logged and the value will be ignored.

Since Ant 1.10.8 the `SOURCE_DATE_EPOCH` environment variable value (if set) will be honoured for reproducible builds. Ant will log a DEBUG message if an invalid value (value that cannot be parsed to an integer), is specified for that environment variable and will instead use the "current" date.

Since Ant 1.10.18 if the `SOURCE_DATE_EPOCH` environment variable is used by the task, the timezone of DSTAMP, TSTAMP and TODAY will be set to UTC. This is also true for nested format elements where in addition the locale defaults to en_US unless they are specified as part of the format element explicitly.

### Parameters

Attribute | Description | Required
--- | --- | ---
prefix | Prefix used for all properties set. | No; default is no prefix

### Parameters specified as nested elements

The task supports a `<format>` nested element that allows a property to be set to the current date and time in a given format. The date/time patterns are as defined in the Java SimpleDateFormat class. The format element also allows offsets to be applied to the time to generate different time values.

Attribute | Description | Required
--- | --- | ---
property | The property to receive the date/time string in the given pattern. | Yes
pattern | The date/time pattern to be used. The values are as defined by the Java SimpleDateFormat class. | Yes
timezone | The timezone to use for displaying time. The values are as defined by the Java TimeZone class. | No
offset | The numeric offset to the current time | No
unit | The unit of the offset to be applied to the current time. Valid values are millisecond second minute hour day week month year | No
locale | The locale used to create date/time string. The general form is language[, country[, variant]] (either variant or both variant and country may be omitted). For more information please refer to documentation for the Locale class. | No

### Examples

Set the standard `DSTAMP`, `TSTAMP`, and `TODAY` properties according to the default formats.

    <tstamp/>

Set the standard properties as well as the property `TODAY_UK` with the date/time pattern d-MMMM-yyyy using English locale (eg. 21-May-2001).

    <tstamp>
        <format property="TODAY_GB" pattern="d-MMMM-yyyy" locale="en,GB"/>
    </tstamp>

Create a timestamp, in the property `touch.time`, 5 hours before the current time. The format in this example is suitable for use with the `<touch>` task. The standard properties are set also.

    <tstamp>
        <format property="touch.time" pattern="MM/dd/yyyy hh:mm aa"
                offset="-5" unit="hour"/>
    </tstamp>

Set three properties with the standard formats, prefixed with start.: `start.DSTAMP`, `start.TSTAMP`, and `start.TODAY`.

    <tstamp prefix="start"/>