date: Usage, Options & Common CI Errors
date prints the current time in any format you specify and can compute relative dates.
date stamps artifacts, builds cache keys, and computes expiry windows in CI. The portability landmine is date arithmetic: GNU date -d and BSD date -v are entirely different.
What it does
date displays the current date and time, formats it with a + format string, converts to UTC with -u, and (on GNU) parses or shifts dates with -d. It is the source of timestamps and time-based cache keys.
Common usage
date +%Y-%m-%d # 2026-06-25
date -u +%Y-%m-%dT%H:%M:%SZ # UTC ISO 8601
date +%s # Unix epoch seconds
date -Iseconds # ISO 8601 with TZ (GNU)
date -d '7 days ago' +%F # GNU date math
date -v-7d +%F # BSD/macOS equivalentOptions
| Item | What it does |
|---|---|
| +FORMAT | strftime format (%Y %m %d %H %M %S %s) |
| -u / --utc | Use UTC |
| -d STRING | Parse/shift a date (GNU only) |
| -v±NunIT | Adjust a date (BSD/macOS only) |
| -I[unit] | ISO 8601 output (GNU) |
Common errors in CI
"date: illegal option -- d" or "invalid date" comes from running GNU syntax (date -d) on BSD/macOS date (which uses -v) or vice versa - the same script breaks across Linux and Mac runners. For portable timestamps stick to date -u +%s or +%Y-%m-%dT%H:%M:%SZ. Time zone affects output unless you pass -u; CI runners may differ in TZ, so pin -u for reproducible cache keys.