Use GNU date for Reliable Timestamps, Time Zones and Safe Checks

You will use GNU date to print an unambiguous timestamp, inspect another time zone, convert Unix seconds, and test a human-readable date without changing the host clock. Allow about 10 minutes. The examples assume a shell, GNU coreutils installed, and an ordinary user account. The installed command on this machine is GNU coreutils 9.4; other releases can differ in small parsing or formatting details.

1. Confirm the command and its version

Start by checking which executable your shell will run. This avoids debugging a different implementation, especially on systems where a BSD date is also available.

$ command -v date
/usr/bin/date
$ date --version | head -2
date (GNU coreutils) 9.4
Copyright (C) 2023 Free Software Foundation, Inc.

Checkpoint: the command should identify itself as GNU coreutils. If it does not, read that implementation's manual page before copying these options.

2. Print a timestamp that scripts can sort

With no date source selected, date prints the current local time. A format string beginning with + controls the output. Use ISO 8601 when another program or person needs to recognise the date without guessing whether a number means a month or a day.

$ date --iso-8601=seconds
2026-09-22T23:28:53+01:00
$ date -u --iso-8601=seconds
2026-09-22T22:28:53+00:00

Your values will differ. The local form includes the host's UTC offset; -u asks for Coordinated Universal Time. For a compact format used in filenames, use explicit format directives:

$ date -u '+%Y%m%dT%H%M%SZ'
20260922T222853Z

In this format, %Y is the year, %m the month, %d the day, %H the hour, %M the minute and %S the second. The final Z is literal text because UTC was selected with -u. Quote the whole format so the shell does not interpret punctuation or spaces.

3. Format a known date without touching the system clock

--date=STRING asks GNU date to describe a supplied time rather than now. The parser accepts formats such as an ISO-like date, relative phrases and Unix seconds. It is useful for reports and checks, but free-form input deserves a visible verification step.

$ date --date='@0' --utc '+%Y-%m-%d %H:%M:%S %Z'
1970-01-01 00:00:00 UTC
$ date --date='2026-09-24 09:00' --iso-8601=minutes
2026-09-24T09:00+01:00
$ date --date='next Thursday' --iso-8601=minutes
2026-09-24T00:00+01:00

The @ form interprets a number as seconds since the Unix Epoch, which is 1970-01-01 00:00 UTC. Relative words are evaluated from the machine's current time and local time zone, so their result changes as time passes. Do not put an untrusted string directly into a command; validate the input and quote it before passing it to a shell command.

For a batch of independent dates, put one date string per line in a file and use --file:

$ printf '%s\n' '2026-09-22 12:00 UTC' '2026-09-24 09:00' > /tmp/date-input.txt
$ date --file=/tmp/date-input.txt --iso-8601=seconds
2026-09-22T12:00:00+00:00
2026-09-24T09:00:00+01:00

The temporary file is input only. Remove it when it is no longer needed with rm -- /tmp/date-input.txt; that deletion is not reversible through date.

4. Inspect another time zone

The TZ environment variable changes how date displays a time without changing the host's configured zone. This is safer than changing system configuration when you only need to answer a scheduling question.

$ TZ='America/Los_Angeles' date '+%Y-%m-%d %H:%M %Z'
2026-09-22 15:28 PDT
$ TZ='Asia/Tokyo' date '+%Y-%m-%d %H:%M %Z'
2026-09-23 07:28 JST

The named zone must be available in the system time-zone database. A zone abbreviation such as PDT is output, not a reliable input identifier. Prefer names such as Europe/London or America/Los_Angeles, because they carry daylight-saving rules.

5. Read a file's modification time

Use --reference=FILE when you want the timestamp associated with an existing file rather than the current time. It does not edit the file.

$ touch /tmp/date-check.txt
$ date --reference=/tmp/date-check.txt --iso-8601=seconds
2026-09-22T23:28:53+01:00
$ stat --format='mtime: %y' /tmp/date-check.txt
mtime: 2026-09-22 23:28:53.000000000 +0100

The displayed precision and wording differ between commands, but both checks refer to the file's modification time. If you need to preserve the file, do not use touch on it: that changes its timestamp. The temporary file in this example can be removed after inspection.

6. Treat system-clock changes as a maintenance action

--set=STRING, or the older positional setting form, changes the host system time. This normally requires elevated privileges and can disrupt logs, scheduled jobs, authentication, databases and other services. Stop before running it on a production host. Prefer the system's time-synchronisation service for a real correction, and coordinate a maintenance window.

If you have a documented reason and a rollback value, record the current clock first, then ask an administrator to set the replacement:

$ date --iso-8601=seconds
2026-09-22T23:28:53+01:00
$ sudo date --set='2026-09-22 23:30:00'
Tue Sep 22 23:30:00 BST 2026
$ date --iso-8601=seconds
2026-09-22T23:30:00+01:00

The output is illustrative: substitute an approved value, not the example blindly. There is no automatic undo. To recover, use the recorded previous value with the same sudo date --set='...' operation, then restore normal time synchronisation according to your host's administration policy. Do not use sudo for the read-only examples above.

7. Diagnose parsing and formatting mistakes

When an input is ambiguous, add --debug. GNU date annotates its interpretation and warns about questionable usage on standard error.

$ date --debug --date='2026-09-24 09:00' --iso-8601=minutes
2026-09-24T09:00+01:00

Keep the diagnostic lines your installed version prints; their wording is version-specific. If the command rejects a string, replace it with an explicit ISO-like date and time zone, then verify the result. Remember that --date, --file, --reference and --resolution are mutually exclusive. --resolution reports the available timestamp resolution, not the current time:

$ date --resolution
0.000000001