datefmt-lite
Convert and format dates/times with zero external APIs — ISO 8601, Unix epoch, RFC 2822, and timezone conversion using only the local date binary and TZ database. Use when you need quick timestamp formatting, epoch conversion, duration arithmetic, or "what time is it in " math without network calls.
datefmt-lite
Small, dependency-free toolkit for turning one timestamp format into another.
Everything runs locally through GNU coreutils date and the TZ database
(/usr/share/zoneinfo). No curl, no API keys, no network.
When to use
- Convert between ISO 8601 ↔ Unix epoch ↔ RFC 2822
- "What time is 2026-09-06 08:28 GMT+8 in UTC / Los Angeles?"
- Add or subtract durations from a date
- Sanity-check cron expressions against real weekdays
- Any shell environment where installing a library is overkill
Prerequisites
- GNU coreutils
date(Linux default; macOS:brew install coreutils, usegdateor prefix commands withg). - TZ database present (
ls /usr/share/zoneinfoshould list regions).
Core recipes
1. Now in common formats
date +%s # Unix epoch seconds (handy for logs)
date -u +"%Y-%m-%dT%H:%M:%SZ" # ISO 8601 UTC (sortable, unambiguous)
date -R # RFC 2822 (email/HTTP headers)
2. Parse "ISO string → epoch"
date -u -d "2026-09-06T08:28:00+08:00" +%s # → 1788654480 (GNU date)
# Reading an epoch back into a human form:
date -u -d "@1788654480" # → Sun Sep 6 00:28:00 UTC 2026
3. Timezone conversion without computing offsets yourself
Pick any zone name from timedatectl list-timezones or /usr/share/zoneinfo.
# "2026-09-06 08:28 GMT+8" expressed in three other zones:
TZ=America/Los_Angeles date -d "2026-09-06 08:28 +0800"
# Sat Sep 5 17:28:00 PDT 2026
TZ=Europe/Berlin date -d "2026-09-06 08:28 +0800"
TZ=Australia/Sydney date -d "2026-09-06 08:28 +0800"
The trick: TZ=... date re-renders the same instant in the target zone,
so you never add/subtract offsets by hand (DST handled automatically).
4. Duration arithmetic
date -d "2026-09-06 + 45 days" +%F # add 45 days → 2026-10-21
date -d "2026-09-06 08:28 - 3 hours" +%s # subtract 3h → epoch
echo $(( $(date -d "2026-10-01" +%s) - $(date -d "2026-09-06" +%s) ))
# seconds between two dates (divide by 86400 for days)
5. Cron-expression sanity check
Before scheduling 30 2 * * 1-5, confirm the weekday names for the run dates:
for d in 2026-09-07 2026-09-08 2026-09-12; do
echo "$d -> $(date -d "$d" +%A) $([ "$(date -d "$d" +%u)" -le 5 ] && echo weekday || echo Weekend)"
done
Common mistakes to avoid
- Writing
TZ=Asia/Shanghai dateinstead of converting a moment. That renders now, not a timestamp you were holding. Usedate -d "<ts>". - Forgetting
-uwhen logging. Local-zone strings in logs sort wrong across DST boundaries and confuse anyone not in your zone. - Relying on
%Falone — always include zone or epoch when persisting.
Verification one-liner
Round-trip check that your toolchain parses what it emits:
e=$(date +%s); iso=$(date -u -d "@$e" +"%Y-%m-%dT%H:%M:%SZ"); \
back=$(date -u -d "$iso" +%s); [ "$e" = "$back" ] && echo "OK"
If this prints OK, your date build handles ISO 8601 correctly.
- Downloads
- Security audit
- Pass
- Last updated
- 2mo ago
- Current version
- v1.0.0
- License
- MIT-0
