doc/rev-list-options: explain "-g" output formats

We document that asking for HEAD@{now} will switch the
output to show HEAD@{timestamp}, but not that specifying
`--date` has a similar effect, or that it can be overridden
with HEAD@{0}. Let's do so.

These rules come from 794151e (reflog-walk: always make
HEAD@{0} show indexed selectors, 2012-05-04), though that is
simply the culmination of years of these heuristics growing
organically.

Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This commit is contained in:
Jeff King 2016-07-22 15:51:32 -04:00 committed by Junio C Hamano
parent 2b68222d72
commit 83c9f95cce

View File

@ -252,10 +252,25 @@ list.
+ +
With `--pretty` format other than `oneline` (for obvious reasons), With `--pretty` format other than `oneline` (for obvious reasons),
this causes the output to have two extra lines of information this causes the output to have two extra lines of information
taken from the reflog. By default, `ref@{Nth}` notation is taken from the reflog. The reflog designator in the output may be shown
used in the output. When the starting commit is specified as as `ref@{Nth}` (where `Nth` is the reverse-chronological index in the
`ref@{now}`, output also uses `ref@{timestamp}` notation reflog) or as `ref@{timestamp}` (with the timestamp for that entry),
instead. Under `--pretty=oneline`, the commit message is depending on a few rules:
+
--
1. If the starting point is specified as `ref@{Nth}`, show the index
format.
+
2. If the starting point was specified as `ref@{now}`, show the
timestamp format.
+
3. If neither was used, but `--date` was given on the command line, show
the timestamp in the format requested by `--date`.
+
4. Otherwise, show the index format.
--
+
Under `--pretty=oneline`, the commit message is
prefixed with this information on the same line. prefixed with this information on the same line.
This option cannot be combined with `--reverse`. This option cannot be combined with `--reverse`.
See also linkgit:git-reflog[1]. See also linkgit:git-reflog[1].