From 2b68222d72fcb899ac87d8d48f066b49b5182f28 Mon Sep 17 00:00:00 2001 From: Jeff King Date: Fri, 22 Jul 2016 15:51:19 -0400 Subject: doc/rev-list-options: clarify "commit@{Nth}" for "-g" option When "log -g" shows "HEAD@{1}", "HEAD@{2}", etc, calling that "commit@{Nth}" is not really accurate. The "HEAD" part is really the refname. By saying "commit", a reader may misunderstand that to mean something related to the specific commit we are showing, not the ref whose reflog we are traversing. While we're here, let's also switch these instances to use literal backticks, as our style guide recommends. As a bonus, that lets us drop some asciidoc quoting. Signed-off-by: Jeff King Signed-off-by: Junio C Hamano --- Documentation/rev-list-options.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index 4f009d4424..6720ff3bbe 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -252,9 +252,9 @@ list. + With `--pretty` format other than `oneline` (for obvious reasons), this causes the output to have two extra lines of information -taken from the reflog. By default, 'commit@\{Nth}' notation is +taken from the reflog. By default, `ref@{Nth}` notation is used in the output. When the starting commit is specified as -'commit@\{now}', output also uses 'commit@\{timestamp}' notation +`ref@{now}`, output also uses `ref@{timestamp}` notation instead. Under `--pretty=oneline`, the commit message is prefixed with this information on the same line. This option cannot be combined with `--reverse`. -- cgit v1.2.3 From 83c9f95cce99bcd383c78d614d614e72a4015e59 Mon Sep 17 00:00:00 2001 From: Jeff King Date: Fri, 22 Jul 2016 15:51:32 -0400 Subject: 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 Signed-off-by: Junio C Hamano --- Documentation/rev-list-options.txt | 23 +++++++++++++++++++---- 1 file changed, 19 insertions(+), 4 deletions(-) diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index 6720ff3bbe..5267ee1937 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -252,10 +252,25 @@ list. + With `--pretty` format other than `oneline` (for obvious reasons), this causes the output to have two extra lines of information -taken from the reflog. By default, `ref@{Nth}` notation is -used in the output. When the starting commit is specified as -`ref@{now}`, output also uses `ref@{timestamp}` notation -instead. Under `--pretty=oneline`, the commit message is +taken from the reflog. The reflog designator in the output may be shown +as `ref@{Nth}` (where `Nth` is the reverse-chronological index in the +reflog) or as `ref@{timestamp}` (with the timestamp for that entry), +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. This option cannot be combined with `--reverse`. See also linkgit:git-reflog[1]. -- cgit v1.2.3 From 522259dc3adf49b59d76ee046a2d1361b171e32f Mon Sep 17 00:00:00 2001 From: Jeff King Date: Fri, 22 Jul 2016 15:51:37 -0400 Subject: doc/pretty-formats: describe index/time formats for %gd The "reflog selector" format changes based on a series of heuristics, and that applies equally to both stock "log -g" output, as well as "--format=%gd". The documentation for "%gd" doesn't cover this. Let's mention the multiple formats and refer the user back to the "-g" section for the complete rules. Signed-off-by: Jeff King Signed-off-by: Junio C Hamano --- Documentation/pretty-formats.txt | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt index 29b19b992f..36a300ae4f 100644 --- a/Documentation/pretty-formats.txt +++ b/Documentation/pretty-formats.txt @@ -147,8 +147,11 @@ endif::git-rev-list[] "U" for a good signature with unknown validity and "N" for no signature - '%GS': show the name of the signer for a signed commit - '%GK': show the key used to sign a signed commit -- '%gD': reflog selector, e.g., `refs/stash@{1}` -- '%gd': shortened reflog selector, e.g., `stash@{1}` +- '%gD': reflog selector, e.g., `refs/stash@{1}` or + `refs/stash@{2 minutes ago`}; the format follows the rules described + for the `-g` option +- '%gd': shortened reflog selector, e.g., `stash@{1}` or + `stash@{2 minutes ago}` - '%gn': reflog identity name - '%gN': reflog identity name (respecting .mailmap, see linkgit:git-shortlog[1] or linkgit:git-blame[1]) -- cgit v1.2.3 From d38c7b2c2ce0116215eb05e11d442e9d03b887f4 Mon Sep 17 00:00:00 2001 From: Jeff King Date: Fri, 22 Jul 2016 15:51:41 -0400 Subject: doc/pretty-formats: explain shortening of %gd The actual shortening rules aren't that interesting and probably not worth getting into (I gloss over them here as "shortened for human readability"). But the fact that %gD shows whatever you gave on the command line is subtle and worth mentioning. Since most people will feed a shortened refname in the first place, it otherwise makes it hard to understand the difference between the two. Signed-off-by: Jeff King Signed-off-by: Junio C Hamano --- Documentation/pretty-formats.txt | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt index 36a300ae4f..b95d67ec01 100644 --- a/Documentation/pretty-formats.txt +++ b/Documentation/pretty-formats.txt @@ -149,9 +149,12 @@ endif::git-rev-list[] - '%GK': show the key used to sign a signed commit - '%gD': reflog selector, e.g., `refs/stash@{1}` or `refs/stash@{2 minutes ago`}; the format follows the rules described - for the `-g` option -- '%gd': shortened reflog selector, e.g., `stash@{1}` or - `stash@{2 minutes ago}` + for the `-g` option. The portion before the `@` is the refname as + given on the command line (so `git log -g refs/heads/master` would + yield `refs/heads/master@{0}`). +- '%gd': shortened reflog selector; same as `%gD`, but the refname + portion is shortened for human readability (so `refs/heads/master` + becomes just `master`). - '%gn': reflog identity name - '%gN': reflog identity name (respecting .mailmap, see linkgit:git-shortlog[1] or linkgit:git-blame[1]) -- cgit v1.2.3 From 1a2a1e8eb93de2b89a32a52980ec7614fe9d154c Mon Sep 17 00:00:00 2001 From: Jeff King Date: Wed, 27 Jul 2016 09:44:41 -0400 Subject: date: document and test "raw-local" mode MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The "raw" format shows a Unix epoch timestamp, but with a timezone tacked on. The timestamp is not _in_ that zone, but it is extra information about the time (by default, the zone the author was in). The documentation claims that "raw-local" does not work. It does, but the end result is rather subtle. Let's describe it in better detail, and test to make sure it works (namely, the epoch time doesn't change, but the zone does). While we are rewording the documentation in this area, let's not use the phrase "does not work" for the remaining option, "--date=relative". It's vague; do we accept it or not? We do accept it, but it has no effect (which is a reasonable outcome). We should also refer to the option not as "--relative" (which is the historical synonym, and does not take "-local" at all), but as "--date=relative". Helped-by: Jakub Narębski Signed-off-by: Jeff King Signed-off-by: Junio C Hamano --- Documentation/rev-list-options.txt | 7 +++++-- t/t0006-date.sh | 1 + 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index 5267ee1937..9215534afa 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -725,8 +725,8 @@ include::pretty-options.txt[] `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 cannot be used with -`--raw` or `--relative`. +e.g. ``2 hours ago''. The `-local` option has no effect for +`--date=relative`. + `--date=local` is an alias for `--date=default-local`. + @@ -747,6 +747,9 @@ 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 in the internal raw Git format `%s %z` format. +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=format:...` feeds the format `...` to your system `strftime`. Use `--date=format:%c` to show the date in your system locale's diff --git a/t/t0006-date.sh b/t/t0006-date.sh index 4c8cf58512..482fec0d7e 100755 --- a/t/t0006-date.sh +++ b/t/t0006-date.sh @@ -47,6 +47,7 @@ check_show short "$TIME" '2016-06-15' check_show default "$TIME" 'Wed Jun 15 16:13:20 2016 +0200' check_show raw "$TIME" '1466000000 +0200' check_show iso-local "$TIME" '2016-06-15 14:13:20 +0000' +check_show raw-local "$TIME" '1466000000 +0000' # arbitrary time absurdly far in the future FUTURE="5758122296 -0400" -- cgit v1.2.3 From 642833db78aa5d7a72677aa9a9b013fb9a880f19 Mon Sep 17 00:00:00 2001 From: Jeff King Date: Fri, 22 Jul 2016 15:51:49 -0400 Subject: date: add "unix" format We already have "--date=raw", which is a Unix epoch timestamp plus a contextual timezone (either the author's or the local). But one may not care about the timezone and just want the epoch timestamp by itself. It's not hard to parse the two apart, but if you are using a pretty-print format, you may want git to show the "finished" form that the user will see. We can accomodate this by adding a new date format, "unix", which is basically "raw" without the timezone. Signed-off-by: Jeff King Signed-off-by: Junio C Hamano --- Documentation/rev-list-options.txt | 4 ++++ builtin/blame.c | 3 +++ cache.h | 3 ++- date.c | 8 ++++++++ t/t0006-date.sh | 2 ++ 5 files changed, 19 insertions(+), 1 deletion(-) diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index 9215534afa..fd86ed12dc 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -751,6 +751,10 @@ 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=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`. Use `--date=format:%c` to show the date in your system locale's preferred format. See the `strftime` manual for a complete list of diff --git a/builtin/blame.c b/builtin/blame.c index 7417edf6ef..002e70f9b5 100644 --- a/builtin/blame.c +++ b/builtin/blame.c @@ -2626,6 +2626,9 @@ parse_done: case DATE_RAW: blame_date_width = sizeof("1161298804 -0700"); break; + case DATE_UNIX: + blame_date_width = sizeof("1161298804"); + break; case DATE_SHORT: blame_date_width = sizeof("2006-10-19"); break; diff --git a/cache.h b/cache.h index c73becbf2d..ace7f70e3b 100644 --- a/cache.h +++ b/cache.h @@ -1223,7 +1223,8 @@ struct date_mode { DATE_ISO8601_STRICT, DATE_RFC2822, DATE_STRFTIME, - DATE_RAW + DATE_RAW, + DATE_UNIX } type; const char *strftime_fmt; int local; diff --git a/date.c b/date.c index 4c7aa9ba85..a996331f5b 100644 --- a/date.c +++ b/date.c @@ -177,6 +177,12 @@ const char *show_date(unsigned long time, int tz, const struct date_mode *mode) struct tm *tm; static struct strbuf timebuf = STRBUF_INIT; + if (mode->type == DATE_UNIX) { + strbuf_reset(&timebuf); + strbuf_addf(&timebuf, "%lu", time); + return timebuf.buf; + } + if (mode->local) tz = local_tzoffset(time); @@ -792,6 +798,8 @@ static enum date_mode_type parse_date_type(const char *format, const char **end) return DATE_NORMAL; if (skip_prefix(format, "raw", end)) return DATE_RAW; + if (skip_prefix(format, "unix", end)) + return DATE_UNIX; if (skip_prefix(format, "format", end)) return DATE_STRFTIME; diff --git a/t/t0006-date.sh b/t/t0006-date.sh index 482fec0d7e..c0c910867d 100755 --- a/t/t0006-date.sh +++ b/t/t0006-date.sh @@ -46,8 +46,10 @@ check_show rfc2822 "$TIME" 'Wed, 15 Jun 2016 16:13:20 +0200' check_show short "$TIME" '2016-06-15' check_show default "$TIME" 'Wed Jun 15 16:13:20 2016 +0200' check_show raw "$TIME" '1466000000 +0200' +check_show unix "$TIME" '1466000000' check_show iso-local "$TIME" '2016-06-15 14:13:20 +0000' check_show raw-local "$TIME" '1466000000 +0000' +check_show unix-local "$TIME" '1466000000' # arbitrary time absurdly far in the future FUTURE="5758122296 -0400" -- cgit v1.2.3 From 442f6fd3d6272b1c7b92e0a24b4be1cf162b4d04 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Wed, 27 Jul 2016 13:07:29 -0700 Subject: date: clarify --date=raw description "... in the internal raw Git format `%s %z` format." was clunky in repeating "format" twice, and would not have helped those who do not immediately get that these are strftime(3) conversion specifiers. Explain them with words, and demote the mention of `%s %z` to a hint to help those who know them. Helped-by: Jeff King Signed-off-by: Junio C Hamano --- Documentation/rev-list-options.txt | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index fd86ed12dc..bee54a6177 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -746,7 +746,11 @@ 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 in the internal raw Git format `%s %z` 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. -- cgit v1.2.3