Home

Awesome

epoch

Action Go Report Card GoDoc

[!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@latest

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

UnitSuffix
Nanosecondsns
Microsecondsus
Millisecondsms
Secondss
Minutesm
Hoursh
DaysD
WeeksW
MonthsM
YearsY
$ 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"