Emacs, scripting and anything text oriented.

Time formatting in Go

Kaushal Modi

A little cheat sheet to help remember the Go time formatting syntax.

Today on Hugo Discourse, I came across the – Why “2006”? – question regarding the use of {{ now.Format "2006" }} in Hugo template. That template simply prints the current year i.e. the time when that template was rendered by Hugo.

As I was answering that, I thought that this was a good time to document this for myself too.. and thus this post.

Time.Format Syntax #

Hugo uses the Go Time.Format method1 for formatting date and time strings. But that format specification uses a strange syntax — You need to associate 1, 2, 3, 4, 5, 6, 7 with date elements as follows:

Table 1: Cryptic dates used for Go Time.Format
NumberField StringsMeaning
101 (with optional leading zero), 1, Jan, Januarymonth
202 (with optional leading zero), 2, Mon, Mondayday
303 (with optional leading zero), 3, 15hour
404 (with optional leading zero), 4minute
505 (with optional leading zero), 5seconds
606, 2006year
-7-0700, -07:00, -07, MSTtimezone
n/aPM (not AM)AM or PM (uppercase)
n/apm (not am)am or pm (lowercase)
n/aanything elseshows up as it is

You can visualize a formatting string "Jan 2 15:04:05 2006 MST" as below:

Jan 2 15:04:05 2006 MST
  1 2  3  4  5    6  -7

Hugo’s dateFormat #

The dateFormat accepts a date/time format using the same syntax.

Here is the signature of that function:

dateFormat "<FORMAT_STRING>" "<DATE_RFC3339>"
  • The <FORMAT_STRING> uses one or more date/time fields as shown in the “Field Strings” column in Table 1. Few examples:
    • “Jan 2 15:04:05 2006 MST”
    • “2006-01-02”
    • “Jan 2, Mon”
    • “It’s 3 O’clock”
  • The <DATE_RFC3339> is a date string compatible with RFC3339. Few example valid date strings:
    • “2017-07-31”
    • “2017-07-31T17:05:38”
    • “2017-07-31T17:05:38Z”
    • “2017-07-31T17:05:38+04:00”
    • “2017-07-31T17:05:38-04:00”

Ordinal dates #

In addition, humanize can be used to generate ordinal date, like “1st”, “2nd”, “3rd”, ..

Examples #

The time string "2018-06-13T11:30:00-04:00" (RFC3339 format) can be output in different formats:

Go Formatting stringOutput
"Jan 2 15:04:05 2006 MST""Jun 13 11:30:00 2018 EDT"
"2006-01-02 03:04pm Monday""2018-06-13 11:30am Wednesday"
"Jan 2, Mon""Jun 13, Wed"
"It's 3 O'clock""It's 11 O'clock"
Below shows examples of printing ordinal dates using a combination of ((dateFormat "2" $dt) | humanize) and (dateFormat "of January" $dt):

Date ($dt)Output
2018-06-01"1st of June"
2018-06-02"2nd of June"
2018-06-03"3rd of June"
2018-06-04"4th of June"
2018-06-10"10th of June"

References #

  1. I am not a Go dev.. let me know if the correct term for that is a “function” or a “method” in Go 😄. Update <2018-11-08 Thu>: Thanks to Mendy in comments, I have now fixed referencing Time.Format as a method↩︎

Versions used: go 1.10.1 , hugo v0.43-DEV-0F1FC01E
Comment by Kaushal Modi on Thu Nov 8, 2018 13:32 EST


It’s a method because it has a receiver!

Thanks for the correction! I now refer to Time.Format as a method.

Comment by Mendy on Thu Nov 8, 2018 01:06 EST

“I am not a Go dev.. let me know if the correct term for that is a “function” or a “method” in Go "

It’s a method because it has a receiver!