[PATCH 1/7] Documentation: extract date-options.txt
- From
Taylor Blau <me@ttaylorr.com>
- Date
- Oct 11, 2022, 00:34 UTC
- Message-ID
- <eaec59daa178c205a59b779c63e411316d8180ed.1665448437.git.me@ttaylorr.com>
- In-Reply-To
- <cover.1665448437.git.me@ttaylorr.com>
A future commit will want to include `--date`-related options in the documentation for `git-shortlog(1)`, but without some of the additional baggage in the usual rev-list-options.txt.
Extract those options to a separate file in Documentation and include it from its original source in rev-list-options.txt.
This patch does not modify the contents of the `--date`-options section of Documentation/rev-list-options.txt.
Signed-off-by: Taylor Blau <me@ttaylorr.com> --- Documentation/date-options.txt | 66 +++++++++++++++++++++++++++++ Documentation/rev-list-options.txt | 67 +----------------------------- 2 files changed, 67 insertions(+), 66 deletions(-) create mode 100644 Documentation/date-options.txt
diff --git a/Documentation/date-options.txt b/Documentation/date-options.txt new file mode 100644 index 0000000000..65896e4b95 --- /dev/null +++ b/Documentation/date-options.txt @@ -0,0 +1,66 @@ +--relative-date:: + Synonym for `--date=relative`. + +--date=<format>:: + Only takes effect for dates shown in human-readable format, such + as when using `--pretty`. `log.date` config variable sets a default + value for the log command's `--date` option. By default, dates + are shown in the original time zone (either committer's or + 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:...` 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` manual for a complete list of +format placeholders. When using `-local`, the correct syntax is +`--date=format-local:...`. + +`--date=default` is the default format, and is similar to +`--date=rfc2822`, with a few exceptions: +-- + - there is no comma after the day-of-week + + - the time zone is omitted when the local time zone is used diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index 1837509566..1cb91dfb9c 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -1033,72 +1033,7 @@ endif::git-rev-list[] include::pretty-options.txt[] ---relative-date:: - Synonym for `--date=relative`. - ---date=<format>:: - Only takes effect for dates shown in human-readable format, such - as when using `--pretty`. `log.date` config variable sets a default - value for the log command's `--date` option. By default, dates - are shown in the original time zone (either committer's or - 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:...` 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` manual for a complete list of -format placeholders. When using `-local`, the correct syntax is -`--date=format-local:...`. - -`--date=default` is the default format, and is similar to -`--date=rfc2822`, with a few exceptions: --- - - there is no comma after the day-of-week - - - the time zone is omitted when the local time zone is used +include::date-options.txt[] ifdef::git-rev-list[] --header::
-- 2.37.0.1.g1379af2e9d