gotwc - Tiny world clock in Go! 🚀

Fast, CLI world clock that displays time zone information using tz database to read valid tz entries.

$ gotwc -h -f tools/samples/tz-small.conf
America/New_York     2023-12-11 12:37:13
America/Los_Angeles  2023-12-11 09:37:13
UTC                  2023-12-11 17:37:13
Europe/London        2023-12-11 17:37:13
Europe/Paris         2023-12-11 18:37:13
Asia/Tokyo           2023-12-12 02:37:13
Australia/Sydney     2023-12-12 04:37:13

Highlights

• 🚀 Fast - 10X times faster than twc.c and 65X times faster than date.¹
  Only ≈ 7 ms for one entry, and ≈ 177 ms for ≈ 600 entries.
• 🔒 Robust - tested to work with all tz database entries, version 2023c.
• 📦 Self-contained - zero dependencies, lightweight (110 lines, 2458 bytes).

Getting Started

Setup

If you have Homebrew installed, just run:

$ brew tap Neved4/homebrew-tap/gotwc

Alternatively, clone the repository:

$ git clone https://github.com/Neved4/gotwc

Then build:

$ go build

Usage

The following usage and options are available:

gotwc [-h] [-f path] [-s format] [-t timezone] ...

Options:
  -f path
      Read config from path (default "$HOME/.config/twc/tz.conf")
  -h
      Print in human-readable format
  -s format
      Set desired time format (e.g. "%Y-%m-%d")
  -t timezone
      specific timezone (e.g. "Asia/Tokyo")

Examples:
  Print Tokyo's date in a human-readable format with YY-MM-DD format:

    $ gotwc -h -s %Y-%m-%d -t Asia/Tokyo
    Asia/Tokyo  2024-01-02 15:04:05
  
  Print date in Los Angeles using an environment variable for the timezone:
  
    $ TZ=America/Los_Angeles gotwc
    2024-01-02T15:04:05-0800

Environment:
  XDG_CONFIG_HOME
    When defined, it will be used to store the tz.conf file.
  TZ
    Timezone to use when displaying dates.

Files:
  ~/.config/twc/tz.conf
    Stores tz database entries to be displayed.

See also:
  environ(7)

Docker

To compile the binary inside a Docker image, run:

docker build .

Compatibility

Runs on Linux, macOS and *BSD systems on both x86_64 and arm64.

Standards

gotwc should run on most POSIX.1-2017² compatible systems and produce ISO 8601³ output.

License

gotwc is licensed under the terms of the MIT License.

See the LICENSE file for details.

Related Projects

• oz/tz - awesome cli time zone helper
• tzdiff - cli timezone diff
• Neved4/twc - tiny world clock in C

Footnotes

1. cfr. date command takes ≈ 931 ms when iterating over ≈ 600 entries. Measured with hyperfine. ↩

2. IEEE Std 1003.1-2017: Standard for Information Technology — Portable Operating System Interface (POSIX®),
   ISO/IEC/IEEE 9945:2009/COR 2:2017. URL: https://pubs.opengroup.org/onlinepubs/9699919799/ ↩

3. ISO 8601: Date and time \ — Representations for information interchange, ISO 8601-1:2019.
   URL: https://www.iso.org/obp/ui/#iso:std:iso:8601:-2:ed-1:v1:en ↩