tsd

View script Copied!

Convert a number to something you can actually read -- paste in a Unix timestamp and get a datetime, or paste in a duration and get hours/minutes/seconds.

The name is short for "timestamp or duration." Give it a number, it figures out which one you meant. Timestamps come back as UTC and local time; durations come back broken into days, hours, minutes, seconds, and sub-second units down to nanoseconds.

Quick start

$ tsd 1609477200
2021-01-01T05:00:00Z
2021-01-01 00:00:00 EST (GMT-5)

$ tsd 1800
30m

Common examples

Check how long something took (milliseconds from a log):

$ tsd 135180 -m
2m 15s 180ms

Break down a duration with mixed units:

$ tsd 7238
2h 0m 38s

Parse a millisecond-precision timestamp (13 digits):

$ tsd 1609477200123
2021-01-01T05:00:00.123Z
2021-01-01 00:00:00.123 EST (GMT-5)

Force a number to be treated as a duration (useful if it happens to be 10 digits and would otherwise be detected as a timestamp):

$ tsd 1609477200 --duration
18628d

Explain 1800 milliseconds:

$ tsd 1800 -m
1s 800ms

How detection works

tsd decides whether the input is a timestamp or a duration based on its digit count:

Unit	Timestamp length	Example
seconds	10 digits	`1609477200`
milliseconds	13 digits	`1609477200123`
microseconds	16 digits	`1609477200123456`
nanoseconds	19 digits	`1609477200123456789`

If the digit count matches exactly, it's a timestamp. Otherwise, it's a duration.

The unit is also inferred from digit count when you don't specify one -- 11 digits is assumed to be milliseconds, 14 digits microseconds, and so on. You can always override with -s, -m, -u, or -n.

Use -d / --duration to force duration interpretation regardless of digit count.

Duration formatting

Zeroes in the middle are preserved so you can see the full breakdown:

$ tsd 172805
2d 0h 0m 5s

$ tsd 86405
1d 0h 0m 5s

Trailing zero units are omitted -- tsd 172800 gives 2d, not 2d 0h 0m 0s:

$ tsd 172800
2d

$ tsd 7200
2h

Reference

All options

Flag	Description
`-s, --sec, --seconds`	Set unit to seconds (default)
`-m, --milli, --milliseconds`	Set unit to milliseconds
`-u, --micro, --microseconds`	Set unit to microseconds
`-n, --nano, --nanoseconds`	Set unit to nanoseconds
`-d, --duration`	Override timestamp detection, treating input as a duration
`-h, --help`	Display help

Options can appear before or after the input number.

Environment variables

Variable	Description
`TSD_LOCALTIME`	Override the local timezone source (default: `/etc/localtime`)

Exit codes

Code	Meaning
0	Success
2	Usage error (missing input, unknown option, multiple units, multiple positionals)

Dependencies

None -- uses only standard Unix utilities (macOS or GNU date).