README
¶
epoch
[!NOTE] I decided to go back to unstable releases. The major version 0 is the newest version, all other major versions are abandoned.
epoch converts unix timestamps to human readable formats and vice versa.
Why?
To convert timestamps to dates, you have to run different commands for different date implementations, such as GNU's, BSD's or Busybox's date implementation. For example, date -d @1267619929 (GNU) vs date -r 1267619929 (BSD), and what about handling nanosecond timestamps? Furthermore, have you ever tried converting a time formatted string such as "2019-01-25 21:51:38 +0100 CET" to a timestamp? Of course, you can do all this somehow, but all ways I've found so far were too cumbersome. This tool tries to solve all this and more with ease:
$ epoch "2019-01-25 21:51:38 +0100 CET"
using seconds as unit
1548449498
$ epoch 1548449498
guessed unit: seconds
2019-01-25 21:51:38 +0100 CET
Convert between timezones:
$ epoch -tz "Europe/Berlin" "Sat Jul 18 15:46:45 UTC 2020"
Sat Jul 18 17:46:45 CEST 2020
Timestamp to formatted string of specific timezone:
$ epoch -tz "America/New_York" 1595088886
guessed unit: seconds
2020-07-18 12:14:46 -0400 EDT
Basic calculations:
$ epoch -calc "-30m +1h -5D +3W -6M +2Y" -tz "local" "2020-07-18 17:46:45.215239 +0200 CEST"
2022-02-03 18:16:45.215239 +0100 CET
The functionallity is implemented as a package and can be used in other programs.
Installation
Precompiled Binaries
Binaries are available for all major platforms. See the releases page. Usually, epoch uses the timezone data from the operating system. When the operating system has no timezone data installed, you can use the 'full' binaries which have this information embedded.
Homebrew
Using the Homebrew package manager for macOS:
brew install sj14/tap/epoch
Manually
It's also possible to install the latest version with go install:
go install github.com/sj14/epoch/cmd/epoch@v0
Usage
Usage of epoch:
-calc string
apply basic time calculations, e.g. '+30m -5h +3M -10Y'
-format string
human readable output format, such as 'rfc3339' (see readme for details)
-quiet
don't output guessed units
-tz string
the timezone to use, e.g. 'Local' (default), 'UTC', or a name corresponding to the IANA Time Zone database, such as 'America/New_York'
-unit string
unit for timestamps: s, ms, us, ns (default "guess")
-version
print version
Examples
Timestamps to human readable format
conversion based on given unit
Use the -unit flag or append the unit at a suffix to the input.
$ epoch -unit s 1548449513
Fri Jan 25 21:51:53 CET 2019
$ epoch 1548449513s
Fri Jan 25 21:51:53 CET 2019
$ epoch -unit ms 1548449513
Sun Jan 18 23:07:29 CET 1970
$ epoch 1548449513ms
Sun Jan 18 23:07:29 CET 1970
$ epoch -unit us 1548449513
Thu Jan 1 01:25:48 CET 1970
$ epoch 1548449513us
Thu Jan 1 01:25:48 CET 1970
$ epoch -unit ns 1548449513
Thu Jan 1 01:00:01 CET 1970
$ epoch 1548449513ns
Thu Jan 1 01:00:01 CET 1970
set the output format
$ epoch -unit ms -format rfc850 1548449513
Sunday, 18-Jan-70 23:07:29 CET
$ epoch -unit ms -format ruby 1548449513
Sun Jan 18 23:07:29 +0100 1970
$ epoch -unit ms -format ansic 1548449513
Sun Jan 18 23:07:29 1970
guess the unit
Guess the unit. Internally, the guesssing is done by comparing the absolute difference of the current epoch timestamps (in s, ms, us, ns) of your machine with the input value. The smallest difference wins.
seconds:
$ epoch 1548449513
guessed unit seconds
2019-01-25 21:51:53 +0100 CET
milliseconds:
$ epoch 1548449513940
guessed unit milliseconds
2019-01-25 21:51:53 +0100 CET
microseconds:
$ epoch 1548449513940562
guessed unit microseconds
2019-01-25 21:51:53.940562 +0100 CET
nanoseconds:
$ epoch 1548449513940562000
guessed unit nanoseconds
2019-01-25 21:51:53.940562 +0100 CET
negative timestamp
$ epoch -- -15484495
guessed unit: seconds
1969-07-05 19:45:05 +0100 CET
using the pipe
$ echo -15484495 | epoch
guessed unit: seconds
1969-07-05 19:45:05 +0100 CET
Formatted input to epoch timestamps
seconds (default when no unit flag given):
$ epoch -unit s "2019-01-25 21:51:38.272173 +0100 CET"
1548449498
milliseconds:
$ epoch -unit ms "2019-01-25 21:51:38.272173 +0100 CET"
1548449498272
microseconds:
$ epoch -unit us "2019-01-25 21:51:38.272173 +0100 CET"
1548449498272173
nanoseconds:
$ epoch -unit ns "2019-01-25 21:51:38.272173 +0100 CET"
1548449498272173000
Arithmetics
| Unit | Suffix |
|---|---|
| Nanoseconds | ns |
| Microseconds | us |
| Milliseconds | ms |
| Seconds | s |
| Minutes | m |
| Hours | h |
| Days | D |
| Weeks | W |
| Months | M |
| Years | Y |
$ epoch -calc "-30m +1h -5D +3W -6M +2Y" -tz "local" "2020-07-18 17:46:45.215239 +0200 CEST"
2022-02-03 18:16:45.215239 +0100 CET
$ epoch -calc "-30m +1h -5D +3W -6M +2Y" "2020-07-18 17:46:45.215239 +0200 CEST"
using seconds as unit
1643908605
Supported Formats
All current Go formats as of 2019-01-26 (https://golang.org/pkg/time/#pkg-constants):
ANSIC = "Mon Jan _2 15:04:05 2006"
UnixDate = "Mon Jan _2 15:04:05 MST 2006"
RubyDate = "Mon Jan 02 15:04:05 -0700 2006"
RFC822 = "02 Jan 06 15:04 MST"
RFC822Z = "02 Jan 06 15:04 -0700" // RFC822 with numeric zone
RFC850 = "Monday, 02-Jan-06 15:04:05 MST"
RFC1123 = "Mon, 02 Jan 2006 15:04:05 MST"
RFC1123Z = "Mon, 02 Jan 2006 15:04:05 -0700" // RFC1123 with numeric zone
RFC3339 = "2006-01-02T15:04:05Z07:00"
RFC3339Nano = "2006-01-02T15:04:05.999999999Z07:00"
Kitchen = "3:04PM"
// Handy time stamps.
Stamp = "Jan _2 15:04:05"
StampMilli = "Jan _2 15:04:05.000"
StampMicro = "Jan _2 15:04:05.000000"
StampNano = "Jan _2 15:04:05.000000000"
// HTTP Timestamp time.RFC1123 but hard-codes GMT as the time zone.
HTTP = "Mon, 02 Jan 2006 15:04:05 GMT"
Directories