git/list[1] front-page[2] threads[3] people[4] search[5] about
 

[PATCH v2 4/5] doc: rev-list-options.adoc: factor out --date alts

From
Kkristofferhaugsbakk@fastmail.com <kristofferhaugsbakk@fastmail.com>
Date
Aug 18, 2026, 09:57 UTC
Message-ID
<V2_doc_--date_alts.bd7@msgid.xyz>
In-Reply-To
<V2_CV_format-rev_three_more_opts.bd3@msgid.xyz>
From: Kristoffer Haugsbakk <code@khaugsbakk.name>

We will introduce `--date` to git-format-rev(1) in the next commit and will need to add it to the documentation. Let’s factor out the option alternatives so that it can be included in git-format-rev(1).

The initial paragraph of this option mentions things like git-log(1). We could make it fit in git-format-rev(1) while not changing it for git-rev-list(1) and related commands with some conditionals like `ifndef`, but writing a dedicated paragraph is simple enough.

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
 .../rev-list-option-date-alternatives.adoc    | 55 ++++++++++++++++++
 Documentation/rev-list-options.adoc           | 56 +------------------
 2 files changed, 56 insertions(+), 55 deletions(-)
 create mode 100644 Documentation/rev-list-option-date-alternatives.adoc
diff --git a/Documentation/rev-list-option-date-alternatives.adoc b/Documentation/rev-list-option-date-alternatives.adoc
new file mode 100644
index 00000000000..141570b1059
--- /dev/null
+++ b/Documentation/rev-list-option-date-alternatives.adoc
@@ -0,0 +1,55 @@
+--
+`--date=relative` shows dates relative to the current time,
+e.g. ``2 hours ago''. The `-local` option has no effect for
+`--date=relative`.
+
+`--date=local` is an alias for `--date=default-local`.
+
+`--date=iso` (or `--date=iso8601`) shows timestamps in a ISO 8601-like format.
+The differences to the strict ISO 8601 format are:
+
+	- a space instead of the `T` date/time delimiter
+	- a space between time and time zone
+	- no colon between hours and minutes of the time zone
+
+`--date=iso-strict` (or `--date=iso8601-strict`) shows timestamps in strict
+ISO 8601 format.
+
+`--date=rfc` (or `--date=rfc2822`) shows timestamps in RFC 2822
+format, often found in email messages.
+
+`--date=short` shows only the date, but not the time, in `YYYY-MM-DD` format.
+
+`--date=raw` shows the date as seconds since the epoch (1970-01-01
+00:00:00 UTC), followed by a space, and then the timezone as an offset
+from UTC (a `+` or `-` with four digits; the first two are hours, and
+the second two are minutes). I.e., as if the timestamp were formatted
+with `strftime("%s %z")`).
+Note that the `-local` option does not affect the seconds-since-epoch
+value (which is always measured in UTC), but does switch the accompanying
+timezone value.
+
+`--date=human` shows the timezone if the timezone does not match the
+current time-zone, and doesn't print the whole date if that matches
+(ie skip printing year for dates that are "this year", but also skip
+the whole date itself if it's in the last few days and we can just say
+what weekday it was).  For older dates the hour and minute is also
+omitted.
+
+`--date=unix` shows the date as a Unix epoch timestamp (seconds since
+1970).  As with `--raw`, this is always in UTC and therefore `-local`
+has no effect.
+
+`--date=format:<format>` feeds the _<format>_ to your system `strftime`,
+except for `%s`, `%z`, and `%Z`, which are handled internally.
+Use `--date=format:%c` to show the date in your system locale's
+preferred format.  See the `strftime`(3) manual for a complete list of
+format placeholders. When using `-local`, the correct syntax is
+`--date=format-local:<format>`.
+
+`--date=default` is the default format, and is based on ctime(3)
+output.  It shows a single line with three-letter day of the week,
+three-letter month, day-of-month, hour-minute-seconds in "HH:MM:SS"
+format, followed by 4-digit year, plus timezone information, unless
+the local time zone is used, e.g. `Thu Jan 1 00:00:00 1970 +0000`.
+--
diff --git a/Documentation/rev-list-options.adoc b/Documentation/rev-list-options.adoc
index fd831f0ec64..6e6093f4747 100644
--- a/Documentation/rev-list-options.adoc
+++ b/Documentation/rev-list-options.adoc
@@ -1132,61 +1132,7 @@ include::pretty-options.adoc[]
 	author's). If `-local` is appended to the format (e.g.,
 	`iso-local`), the user's local time zone is used instead.
 +
---
-`--date=relative` shows dates relative to the current time,
-e.g. ``2 hours ago''. The `-local` option has no effect for
-`--date=relative`.
-
-`--date=local` is an alias for `--date=default-local`.
-
-`--date=iso` (or `--date=iso8601`) shows timestamps in a ISO 8601-like format.
-The differences to the strict ISO 8601 format are:
-
-	- a space instead of the `T` date/time delimiter
-	- a space between time and time zone
-	- no colon between hours and minutes of the time zone
-
-`--date=iso-strict` (or `--date=iso8601-strict`) shows timestamps in strict
-ISO 8601 format.
-
-`--date=rfc` (or `--date=rfc2822`) shows timestamps in RFC 2822
-format, often found in email messages.
-
-`--date=short` shows only the date, but not the time, in `YYYY-MM-DD` format.
-
-`--date=raw` shows the date as seconds since the epoch (1970-01-01
-00:00:00 UTC), followed by a space, and then the timezone as an offset
-from UTC (a `+` or `-` with four digits; the first two are hours, and
-the second two are minutes). I.e., as if the timestamp were formatted
-with `strftime("%s %z")`).
-Note that the `-local` option does not affect the seconds-since-epoch
-value (which is always measured in UTC), but does switch the accompanying
-timezone value.
-
-`--date=human` shows the timezone if the timezone does not match the
-current time-zone, and doesn't print the whole date if that matches
-(ie skip printing year for dates that are "this year", but also skip
-the whole date itself if it's in the last few days and we can just say
-what weekday it was).  For older dates the hour and minute is also
-omitted.
-
-`--date=unix` shows the date as a Unix epoch timestamp (seconds since
-1970).  As with `--raw`, this is always in UTC and therefore `-local`
-has no effect.
-
-`--date=format:<format>` feeds the _<format>_ to your system `strftime`,
-except for `%s`, `%z`, and `%Z`, which are handled internally.
-Use `--date=format:%c` to show the date in your system locale's
-preferred format.  See the `strftime`(3) manual for a complete list of
-format placeholders. When using `-local`, the correct syntax is
-`--date=format-local:<format>`.
-
-`--date=default` is the default format, and is based on ctime(3)
-output.  It shows a single line with three-letter day of the week,
-three-letter month, day-of-month, hour-minute-seconds in "HH:MM:SS"
-format, followed by 4-digit year, plus timezone information, unless
-the local time zone is used, e.g. `Thu Jan 1 00:00:00 1970 +0000`.
---
+include::rev-list-option-date-alternatives.adoc[]
 
 ifdef::git-rev-list[]
 `--header`::
-- 
2.55.0.13.g85d2d65e389
Previous: kristofferhaugsbakk@fastmail.comNext: kristofferhaugsbakk@fastmail.com
Message 16 of 25 in “format-rev: add --abbrev, --color, and --date”
  1. 0/4 format-rev: add --abbrev, --color, and --datekristofferhaugsbakk@fastmail.com, Aug 13, 2026
  2. 1/4 format-rev: use lower case for opts descriptionkristofferhaugsbakk@fastmail.com, Aug 13, 2026
  3. 2/4 format-rev: factor option variables into a structkristofferhaugsbakk@fastmail.com, Aug 13, 2026
  4. Junio C HamanoAug 13, 2026
  5. Kristoffer HaugsbakkAug 14, 2026
  6. 3/4 doc: rev-list-options.adoc: factor out --date altskristofferhaugsbakk@fastmail.com, Aug 13, 2026
  7. 4/4 format-rev: learn --abbrev, --color, and --datekristofferhaugsbakk@fastmail.com, Aug 13, 2026
  8. Junio C HamanoAug 15, 2026
  9. Kristoffer HaugsbakkAug 17, 2026
  10. Junio C HamanoAug 17, 2026
  11. Kristoffer HaugsbakkAug 18, 2026
  12. 0/5 format-rev: add --abbrev, --color, and --datekristofferhaugsbakk@fastmail.com, Aug 18, 2026
  13. 1/5 format-rev: use lower case for opts descriptionkristofferhaugsbakk@fastmail.com, Aug 18, 2026
  14. 2/5 format-rev: place BUG calls first in callbackkristofferhaugsbakk@fastmail.com, Aug 18, 2026
  15. 3/5 format-rev: factor option variables into a structkristofferhaugsbakk@fastmail.com, Aug 18, 2026
  16. 4/5 doc: rev-list-options.adoc: factor out --date altskristofferhaugsbakk@fastmail.com, Aug 18, 2026
  17. 5/5 format-rev: learn --abbrev, --color, and --datekristofferhaugsbakk@fastmail.com, Aug 18, 2026
  18. Junio C HamanoAug 26, 2026
  19. Ben KnobleSep 3, 2026
  20. Kristoffer HaugsbakkSep 3, 2026
  21. Junio C HamanoNov 2, 2026
  22. Kristoffer HaugsbakkNov 2, 2026
  23. Ben KnobleNov 2, 2026
  24. Kristoffer HaugsbakkNov 3, 2026
  25. D. Ben KnobleNov 7, 2026

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.