> ## Documentation Index
> Fetch the complete documentation index at: https://errand.nuvrel.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# formatdate

> Format a timestamp using a layout string.

`formatdate(format, time)` formats `time` using the given `format` string. `time` must be an RFC 3339 timestamp string.

## Signature

```
formatdate(format string, time string) string
```

## Format tokens

| Token  | Description                     | Example   |
| ------ | ------------------------------- | --------- |
| `YYYY` | Four-digit year                 | `2024`    |
| `YY`   | Two-digit year                  | `24`      |
| `MM`   | Two-digit month                 | `01`-`12` |
| `MMM`  | Three-letter month abbreviation | `Jan`     |
| `MMMM` | Full month name                 | `January` |
| `DD`   | Two-digit day                   | `01`-`31` |
| `D`    | Day without leading zero        | `1`-`31`  |
| `hh`   | Two-digit hour (24-hour)        | `00`-`23` |
| `mm`   | Two-digit minute                | `00`-`59` |
| `ss`   | Two-digit second                | `00`-`59` |
| `ZZZ`  | Timezone abbreviation           | `UTC`     |
| `Z`    | Timezone offset                 | `+00:00`  |

## Example

Stamp a release artifact with a timestamp passed in from the environment or CI system:

```hcl theme={null}
variable "version" {
  type = string
}

variable "build_timestamp" {
  description = "RFC 3339 build timestamp (e.g. 2024-03-15T10:30:00Z)"
  type        = string
}

computed "release_date" {
  description = "Date portion of the build timestamp"
  expression  = formatdate("YYYY-MM-DD", var.build_timestamp)
}

task "package" {
  description = "Build a dated release archive"
  commands = [
    "go build -o bin/app ./cmd/app",
    "tar -czf releases/app-${var.version}-${computed.release_date}.tar.gz bin/app",
  ]
}
```

Pass the timestamp at run time:

```bash theme={null}
errand run package --var version=1.4.2 --var build_timestamp=2024-03-15T10:30:00Z
```

The archive name becomes `app-1.4.2-2024-03-15.tar.gz`.

## Notes

* `time` must be a valid RFC 3339 string (e.g. `2024-03-15T10:30:00Z`). An invalid format produces an error at evaluation time.
* `formatdate` does not perform timezone conversion. The output timezone depends on the input timestamp.