[PATCH] pretty: add format specifiers: %gr, %gt, %gI, gi

[PATCH] pretty: add format specifiers: %gr, %gt, %gI, gi

[Theodore Ts'o]

Add new format specifiers which allow the printing of reflog
timestamp.  This allows us to know when operations which change HEAD
take place (e.g., guilt pop -a, which does the equivalent of a "git
reset --hard commit"), since using %cr will display when the commit
was originally made, instead of when HEAD was moved to that commit.

This allows something like:

git log -g --pretty=format:'%Cred%h%Creset %gd %gs %Cgreen(%gr)%Creset %s' --abbrev-commit

to provide what (for me) is a much more useful "git reflog" type of
report.

Signed-off-by: Theodore Ts'o <tytso@mit.edu>
---
 Documentation/pretty-formats.txt |  4 ++++
 cache.h                          |  1 +
 date.c                           |  2 +-
 pretty.c                         | 18 ++++++++++++++++
 reflog-walk.c                    | 45 ++++++++++++++++++++++++++++++----------
 reflog-walk.h                    |  3 +++
 6 files changed, 61 insertions(+), 12 deletions(-)

diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt
index 29b19b9..7927754 100644
--- a/Documentation/pretty-formats.txt
+++ b/Documentation/pretty-formats.txt
@@ -156,6 +156,10 @@ endif::git-rev-list[]
 - '%gE': reflog identity email (respecting .mailmap, see
   linkgit:git-shortlog[1] or linkgit:git-blame[1])
 - '%gs': reflog subject
+- '%gr': reflog date, relative
+- '%gt': reflog date, UNIX timestamp
+- '%gi': reflog date, ISO 8601-like format
+- '%gI': reflog date, strict ISO 8601 format
 - '%Cred': switch color to red
 - '%Cgreen': switch color to green
 - '%Cblue': switch color to blue
diff --git a/cache.h b/cache.h
index f1dc289..5dd2805 100644
--- a/cache.h
+++ b/cache.h
@@ -1237,6 +1237,7 @@ struct date_mode {
 #define DATE_MODE(t) date_mode_from_type(DATE_##t)
 struct date_mode *date_mode_from_type(enum date_mode_type type);
 
+time_t gm_time_t(unsigned long time, int tz);
 const char *show_date(unsigned long time, int timezone, const struct date_mode *mode);
 void show_date_relative(unsigned long time, int tz, const struct timeval *now,
 			struct strbuf *timebuf);
diff --git a/date.c b/date.c
index 4c7aa9b..f98502e 100644
--- a/date.c
+++ b/date.c
@@ -39,7 +39,7 @@ static const char *weekday_names[] = {
 	"Sundays", "Mondays", "Tuesdays", "Wednesdays", "Thursdays", "Fridays", "Saturdays"
 };
 
-static time_t gm_time_t(unsigned long time, int tz)
+time_t gm_time_t(unsigned long time, int tz)
 {
 	int minutes;
 
diff --git a/pretty.c b/pretty.c
index 330a5e0..eb1f44e 100644
--- a/pretty.c
+++ b/pretty.c
@@ -1212,6 +1212,24 @@ static size_t format_commit_one(struct strbuf *sb, /* in UTF-8 */
 						    placeholder[1],
 						    c->pretty_ctx->reflog_info,
 						    &c->pretty_ctx->date_mode);
+		case 'r':	/* date, relative */
+			strbuf_addstr(sb,
+				show_reflog_date(c->pretty_ctx->reflog_info,
+					DATE_MODE(RELATIVE)));
+			return 2;
+		case 'i':	/* date, ISO 8601-like */
+			strbuf_addstr(sb,
+				show_reflog_date(c->pretty_ctx->reflog_info,
+					DATE_MODE(ISO8601)));
+			return 2;
+		case 'I':	/* date, ISO 8601 strict */
+			strbuf_addstr(sb,
+				show_reflog_date(c->pretty_ctx->reflog_info,
+					DATE_MODE(ISO8601_STRICT)));
+			return 2;
+		case 't':
+			strbuf_addf(sb, "%lu", get_reflog_time_t(c->pretty_ctx->reflog_info));
+			return 2;
 		}
 		return 0;	/* unknown %g placeholder */
 	case 'N':
diff --git a/reflog-walk.c b/reflog-walk.c
index a246af2..d0aa2d0 100644
--- a/reflog-walk.c
+++ b/reflog-walk.c
@@ -292,17 +292,24 @@ void get_reflog_selector(struct strbuf *sb,
 	strbuf_addch(sb, '}');
 }
 
-void get_reflog_message(struct strbuf *sb,
-			struct reflog_walk_info *reflog_info)
+static struct reflog_info *get_reflog_info(struct reflog_walk_info *reflog_info)
 {
 	struct commit_reflog *commit_reflog = reflog_info->last_commit_reflog;
-	struct reflog_info *info;
-	size_t len;
 
 	if (!commit_reflog)
-		return;
+		return NULL;
+
+	return &commit_reflog->reflogs->items[commit_reflog->recno+1];
+}
 
-	info = &commit_reflog->reflogs->items[commit_reflog->recno+1];
+void get_reflog_message(struct strbuf *sb,
+			struct reflog_walk_info *reflog_info)
+{
+	struct reflog_info *info = get_reflog_info(reflog_info);
+	size_t len;
+
+	if (!info)
+		return NULL;
 	len = strlen(info->message);
 	if (len > 0)
 		len--; /* strip away trailing newline */
@@ -311,16 +318,32 @@ void get_reflog_message(struct strbuf *sb,
 
 const char *get_reflog_ident(struct reflog_walk_info *reflog_info)
 {
-	struct commit_reflog *commit_reflog = reflog_info->last_commit_reflog;
-	struct reflog_info *info;
+	struct reflog_info *info = get_reflog_info(reflog_info);
 
-	if (!commit_reflog)
+	if (!info)
 		return NULL;
-
-	info = &commit_reflog->reflogs->items[commit_reflog->recno+1];
 	return info->email;
 }
 
+unsigned long get_reflog_time_t(struct reflog_walk_info *reflog_info)
+{
+	struct reflog_info *info = get_reflog_info(reflog_info);
+
+	if (!info)
+		return NULL;
+	return gm_time_t(info->timestamp, info->tz);
+}
+
+const char *show_reflog_date(struct reflog_walk_info *reflog_info,
+			     const struct date_mode *mode)
+{
+	struct reflog_info *info = get_reflog_info(reflog_info);
+
+	if (!info)
+		return NULL;
+	return show_date(info->timestamp, info->tz, mode);
+}
+
 void show_reflog_message(struct reflog_walk_info *reflog_info, int oneline,
 			 const struct date_mode *dmode, int force_date)
 {
diff --git a/reflog-walk.h b/reflog-walk.h
index 27886f7..aaccc58 100644
--- a/reflog-walk.h
+++ b/reflog-walk.h
@@ -15,6 +15,9 @@ extern void show_reflog_message(struct reflog_walk_info *info, int,
 extern void get_reflog_message(struct strbuf *sb,
 		struct reflog_walk_info *reflog_info);
 extern const char *get_reflog_ident(struct reflog_walk_info *reflog_info);
+extern unsigned long get_reflog_time_t(struct reflog_walk_info *reflog_info);
+extern const char *show_reflog_date(struct reflog_walk_info *reflog_info,
+				    const struct date_mode *mode);
 extern void get_reflog_selector(struct strbuf *sb,
 		struct reflog_walk_info *reflog_info,
 		const struct date_mode *dmode, int force_date,
-- 
2.9.0.243.g5c589a7.dirty

Re: [PATCH] pretty: add format specifiers: %gr, %gt, %gI, gi

[Jeff King]

On Sun, Jul 10, 2016 at 01:54:02AM -0400, Theodore Ts'o wrote:

> Add new format specifiers which allow the printing of reflog
> timestamp.  This allows us to know when operations which change HEAD
> take place (e.g., guilt pop -a, which does the equivalent of a "git
> reset --hard commit"), since using %cr will display when the commit
> was originally made, instead of when HEAD was moved to that commit.

Hrm. You can already get dates like:

  git log --date=relative -g --format=%gd

(or --date=iso, or whatever). But:

  1. It's always branch@{...date...}, not just ...date...

  2. It takes over %gd, so this:

> git log -g --pretty=format:'%Cred%h%Creset %gd %gs %Cgreen(%gr)%Creset %s' --abbrev-commit

can't be done (you cannot show both HEAD@{0} and "5 minutes ago").

So the status quo definitely isn't as flexible as it could be. I'm just
not excited about adding a bunch more obscure two-character codes that
don't even cover all of the possible date formats (I know we have the
same problem for the author/committer timestamps, but we are stuck with
those for historical reasons).

I wonder if a better approach would be:

  1. In the short term, add specific designators for the fields you'd
     want. One for HEAD@{n} that is unaffected by date, as %gd is (or
     even one for the branch-name and one for "n"). And one for the
     reflog date, by itself, in whatever format --date= asked for.

     That would let you do your format above, though it does not let you
     show the reflog date in multiple formats.

  2. In the long term, teach log's pretty formatter to handle less
     obscure syntax, that can include arguments. The pretty-printer in
     for-each-ref can already do "%(authordate:relative)", and accepts
     any date-format that git knows about. We should do the same here.

I dunno. Your patch does not make either of those paths _harder_, and it
is not like there isn't precedent. It just bloats the user-visible
interface with stuff that would later become redundant (but that we
can't get rid of because of backwards compatibility).

-Peff

Re: [PATCH] pretty: add format specifiers: %gr, %gt, %gI, gi

[Theodore Ts'o]

On Sun, Jul 10, 2016 at 02:16:45AM -0400, Jeff King wrote:
> I wonder if a better approach would be:
> 
>   1. In the short term, add specific designators for the fields you'd
>      want. One for HEAD@{n} that is unaffected by date, as %gd is (or
>      even one for the branch-name and one for "n"). And one for the
>      reflog date, by itself, in whatever format --date= asked for.
> 
>      That would let you do your format above, though it does not let you
>      show the reflog date in multiple formats.

Hrm, maybe.  I didn't realize that %gd and %gD displayed something
very different if --date is specified.  Is this documented?  I looked
everywhere, and the closest I could find is a mention in the
description of -g that if you specify commit@{now}, the output will
use commit@{timestamp} notation --- but that's different from
--date=xxx, and it doesn't actually specify which pretty-printer
format string this affects, although I suppose that's not that hard to
infer.

One other thing I'll note in passing is that the --date notation
doesn't support Unix timestamps.  So you can't actually do the
equivalent of %gt as proposed in this patch.

I'm not sure what designators we'd use for a HEAD@{n} that is
uneffected by date, and as far as which arbitrary two-letter code for
"reflog date in the default date format", we can't use %gd (ala %ad or
%cd), since it's already spoken for.  %gr, %gt, etc., at least have
the advantage that they are somewhat orthogonal to %ar/%at, %cr/%ct,
etc.

So I definitely understand the concern about the PP format string
being somewhat creaky, and obscure.  It's not entirely clearly to me
that adding the new designators actually doesn't add more bloat or
non-orthogonality.  I suppose we could add %gb for branch name, and
%gU for the HEAD@{n} nUm --- since %gn and %gN are already spoken for
--- and then use %gt for the reflog date in the default date format.
So that only adds three new two-letter formats, instead of the four in
my patch.

(BTW, I really only care about %gt and %gr --- so if the concern is
bloat, we could just add those two specifiers.  I just added %gi and
%gI because it wasn't hard, and I thought orthoganlity was better
where it was possible.)

>   2. In the long term, teach log's pretty formatter to handle less
>      obscure syntax, that can include arguments. The pretty-printer in
>      for-each-ref can already do "%(authordate:relative)", and accepts
>      any date-format that git knows about. We should do the same here.

See the above comment about our currently not supporting Unix time as
one of the date-formats.  So if the goal was to make the proposed new
pretty formatter be a superset of the percent expansion rules, there
isn't really a clean way of doing %at.

One possibility is %{authordate:format:%s} --- but it suffers from two
drawbacks:

(a) It's kind of ugly/obscure, since it gets us back to using
not-so-human-friendly percent expansions.

(b) It's not portable, since apparently %s isn't one of the strftime
formats which is guaranteed by the Single Unix Specification or the
C99 standard.  (Maybe it is implemented in all of the platforms we
care about (e.g., Windows, MacOS, etc.), though.)


One other long-term thought.  Maybe past a certain point, we should
just make it easy to get the data from git-log into a perl or pythons
script, where it becomes possible to do conditionals, more flexible
padding rules, etc.  So some kind of --format=yaml or --format=json
sort of thing.  Some interesting ideas of how we could do this can be
found here:

	https://cloud.google.com/sdk/gcloud/reference/topic/formats

... although I doubt whether git would ever want to do the equivalent of:

gcloud compute images list  --format='table[box,title=Images](name:sort=1,family)'

which will print something like this:

+------------------------------------------------------------+
|                           Images                           |
+------------------------------------------+-----------------+
|                   NAME                   |      FAMILY     |
+------------------------------------------+-----------------+
| centos-6-v20160629                       | centos-6        |
| centos-7-v20160629                       | centos-7        |
| coreos-alpha-1097-0-0-v20160702          | coreos-alpha    |
| coreos-beta-1068-3-0-v20160627           | coreos-beta     |
| coreos-stable-1010-6-0-v20160628         | coreos-stable   |
| debian-8-jessie-v20160629                | debian-8        |
| freebsd-101-release-amd64-20150101032704 |                 |
| opensuse-13-2-v20160222                  |                 |
| opensuse-leap-42-1-v20160302             |                 |
| rhel-6-v20160629                         | rhel-6          |
| rhel-7-v20160629                         | rhel-7          |
| sles-11-sp4-v20160301                    |                 |
| sles-12-sp1-v20160301                    |                 |
| ubuntu-1204-precise-v20160627            | ubuntu-1204-lts |
| ubuntu-1404-trusty-v20160627             | ubuntu-1404-lts |
| ubuntu-1510-wily-v20160627               | ubuntu-1510     |
| ubuntu-1604-xenial-v20160627             | ubuntu-1604-lts |
| windows-server-2008-r2-dc-v20160623      | windows-2008-r2 |
| windows-server-2012-r2-dc-v20160623      | windows-2012-r2 |
| xfstests-201607030209                    | xfstests        |
+------------------------------------------+-----------------+

and will even use fancy graphics characters if you're using a terminal
which supports them.  :-)

						- Ted

Re: [PATCH] pretty: add format specifiers: %gr, %gt, %gI, gi

[Duy Nguyen]

On Sun, Jul 10, 2016 at 4:26 PM, Theodore Ts'o <tytso@mit.edu> wrote:
> One other long-term thought.  Maybe past a certain point, we should
> just make it easy to get the data from git-log into a perl or pythons
> script, where it becomes possible to do conditionals, more flexible
> padding rules, etc.  So some kind of --format=yaml or --format=json
> sort of thing.

I thought libgit2 would already give you all the information you need.

> Some interesting ideas of how we could do this can be
> found here:
>
>         https://cloud.google.com/sdk/gcloud/reference/topic/formats
>
> ... although I doubt whether git would ever want to do the equivalent of:
>
> gcloud compute images list  --format='table[box,title=Images](name:sort=1,family)'
>
> which will print something like this:
>
> +------------------------------------------------------------+
> |                           Images                           |
> +------------------------------------------+-----------------+
> |                   NAME                   |      FAMILY     |
> +------------------------------------------+-----------------+
> | centos-6-v20160629                       | centos-6        |
> | centos-7-v20160629                       | centos-7        |
> | coreos-alpha-1097-0-0-v20160702          | coreos-alpha    |
> | coreos-beta-1068-3-0-v20160627           | coreos-beta     |
> | coreos-stable-1010-6-0-v20160628         | coreos-stable   |
> | debian-8-jessie-v20160629                | debian-8        |
> | freebsd-101-release-amd64-20150101032704 |                 |
> | opensuse-13-2-v20160222                  |                 |
> | opensuse-leap-42-1-v20160302             |                 |
> | rhel-6-v20160629                         | rhel-6          |
> | rhel-7-v20160629                         | rhel-7          |
> | sles-11-sp4-v20160301                    |                 |
> | sles-12-sp1-v20160301                    |                 |
> | ubuntu-1204-precise-v20160627            | ubuntu-1204-lts |
> | ubuntu-1404-trusty-v20160627             | ubuntu-1404-lts |
> | ubuntu-1510-wily-v20160627               | ubuntu-1510     |
> | ubuntu-1604-xenial-v20160627             | ubuntu-1604-lts |
> | windows-server-2008-r2-dc-v20160623      | windows-2008-r2 |
> | windows-server-2012-r2-dc-v20160623      | windows-2012-r2 |
> | xfstests-201607030209                    | xfstests        |
> +------------------------------------------+-----------------+
>
> and will even use fancy graphics characters if you're using a terminal
> which supports them.  :-)

Putting everything in columns is my thing :) We can do something like
that. It should not be so hard to put titles on top and draw some
lines, I think, if you set fixed column widths. I'm just not sure if
it will be really helpful. What sort of use case do you have in mind
(besides git-log --oneline with customizable columns)?
-- 
Duy

Re: [PATCH] pretty: add format specifiers: %gr, %gt, %gI, gi

[Theodore Ts'o]

On Sun, Jul 10, 2016 at 06:05:31PM +0200, Duy Nguyen wrote:
> On Sun, Jul 10, 2016 at 4:26 PM, Theodore Ts'o <tytso@mit.edu> wrote:
> > One other long-term thought.  Maybe past a certain point, we should
> > just make it easy to get the data from git-log into a perl or pythons
> > script, where it becomes possible to do conditionals, more flexible
> > padding rules, etc.  So some kind of --format=yaml or --format=json
> > sort of thing.
> 
> I thought libgit2 would already give you all the information you need.

libgit2 isn't really all that useful if you are writing a shell
script.  Even from perl or python, setting up SWIG bindings and then
linking libgit2 into perl or python isn't exactly the most convenient
thing in the world.

Also, my original use case was something I could drop into
~/.gitconfig as an git alias, although I don't object to having a
separate shell script if that was the only way to do what I wanted.

> Putting everything in columns is my thing :) We can do something like
> that. It should not be so hard to put titles on top and draw some
> lines, I think, if you set fixed column widths. I'm just not sure if
> it will be really helpful. What sort of use case do you have in mind
> (besides git-log --oneline with customizable columns)?

I didn't; it was the example of something which was over the top.  :-)

That being said, it is nice if you can have columns where the
pretty-printer auto-sizes the column widths.  Most databases which
have a REP loop for SQL statements will do this, as does gcloud's
--format='table[box]...' scheme.  That unfortunately means a two-pass
scheme, although I could imagine something which looks at the first N
commits to be printed, figured out column widths, and then either
truncates or autowraps if there are commits after the first N which
have require a field wider than what was autosized.

It may be too much to think that all of this should be in git's core
implementation, though.  This is where it might be simpler to easily
get the information into perl or python, and then do the final
formatting in perl/pyhton.  Hence my suggestion for some kind of yaml
or json format.  Although I suppose a CPAN or Python Module that
dlopen's libgit2 could also work, so long as it was super-easy for
someone who just wants to create a git-log like report can just do so
without having to create their own C program or C language bindings to
libgit2....

					- Ted

Re: [PATCH] pretty: add format specifiers: %gr, %gt, %gI, gi

[Jeff King]

On Sun, Jul 10, 2016 at 10:26:22AM -0400, Theodore Ts'o wrote:

> On Sun, Jul 10, 2016 at 02:16:45AM -0400, Jeff King wrote:
> > I wonder if a better approach would be:
> > 
> >   1. In the short term, add specific designators for the fields you'd
> >      want. One for HEAD@{n} that is unaffected by date, as %gd is (or
> >      even one for the branch-name and one for "n"). And one for the
> >      reflog date, by itself, in whatever format --date= asked for.
> > 
> >      That would let you do your format above, though it does not let you
> >      show the reflog date in multiple formats.
> 
> Hrm, maybe.  I didn't realize that %gd and %gD displayed something
> very different if --date is specified.  Is this documented?  I looked
> everywhere, and the closest I could find is a mention in the
> description of -g that if you specify commit@{now}, the output will
> use commit@{timestamp} notation --- but that's different from
> --date=xxx, and it doesn't actually specify which pretty-printer
> format string this affects, although I suppose that's not that hard to
> infer.

I couldn't find anything beyond the bit that you mentioned. So no
explanation of "--date", and no mention that  "%gd" is affected by the
usual "-g" output rules. I have two patches to improve that.

> One other thing I'll note in passing is that the --date notation
> doesn't support Unix timestamps.  So you can't actually do the
> equivalent of %gt as proposed in this patch.

We have "--date=raw", but that's not _quite_ the same, as it includes
the timezone. I think we should have "--date=unix" for this case. Patch
to follow.

> I'm not sure what designators we'd use for a HEAD@{n} that is
> uneffected by date, and as far as which arbitrary two-letter code for
> "reflog date in the default date format", we can't use %gd (ala %ad or
> %cd), since it's already spoken for.  %gr, %gt, etc., at least have
> the advantage that they are somewhat orthogonal to %ar/%at, %cr/%ct,
> etc.

Yeah, I'd have hoped for %gd, as well. One thing I think we should move
towards in the long run is giving more readable names to our
placeholders for git-log, the way for-each-ref and cat-file do (but
keeping the existing ones for compatibility and as a shorthand).

So ideally the answer in the long run is:

  %(reflog-ref)@{%(reflog-index)}

or possibly:

  %(reflog:index)

for the whole thing. Or something like that. I haven't thought that hard
about the exact syntax.

But anyway, I don't necessarily expect you to dig into that much larger
topic.

> So I definitely understand the concern about the PP format string
> being somewhat creaky, and obscure.  It's not entirely clearly to me
> that adding the new designators actually doesn't add more bloat or
> non-orthogonality.  I suppose we could add %gb for branch name, and
> %gU for the HEAD@{n} nUm --- since %gn and %gN are already spoken for
> --- and then use %gt for the reflog date in the default date format.
> So that only adds three new two-letter formats, instead of the four in
> my patch.
> 
> (BTW, I really only care about %gt and %gr --- so if the concern is
> bloat, we could just add those two specifiers.  I just added %gi and
> %gI because it wasn't hard, and I thought orthoganlity was better
> where it was possible.)

To me it's less about the number, and more the issue that:

  1. It's half-implemented. Why can we do format X, but not format Y
     (for that matter, why can you do %ct, but there is no --date format
     that matches it?). That sort of non-orthogonality ends up
     frustrating for users and makes git look creaky and poorly thought
     out.

  2. Every shorthand we pick, especially for things that aren't commonly
     used, eats up the namespace. If I were designing from scratch, I'd
     say the reflog selector shouldn't be %gd; that should be reserved
     for symmetry with %ad and %cd.

     I think your patch is not really an offender here, though; if
     anything it's helping symmetry.

> One possibility is %{authordate:format:%s} --- but it suffers from two
> drawbacks:

Yeah, I agree that's pretty horrid. We should have "Unix timestamp" as a
first-class format.

> One other long-term thought.  Maybe past a certain point, we should
> just make it easy to get the data from git-log into a perl or pythons
> script, where it becomes possible to do conditionals, more flexible
> padding rules, etc.  So some kind of --format=yaml or --format=json
> sort of thing.  Some interesting ideas of how we could do this can be
> found here:

I do like that idea, though I think that's a somewhat orthogonal
concept, just because this kind of pretty-format stuff is used in two
ways. One, to easily get it into another script which will do something
clever with it. And two, to make nicer formats for everyday use for
things like "git log", "git branch -v", and so on.

The two needs only intersect when your plan is to get it into a perl
script which will do the nice formatting. :)

So I think --format=json is a great idea for getting it into a separate
script, but it doesn't help people much who just want to customize their
git-log output. As an aside, there was talk and some patches long ago
about having a json-format for a lot of different commands. E.g., not
just "git log", but "git status --porcelain", etc.  I like the general
idea; line-oriented is convenient with the usual shell tools, but the
quoting is sometimes a nightmare (and I think the "status --porcelain"
output is even context-sensitive, which is horrible to parse). If you're
interested, I think this is the probably the most relevant thread:

  http://thread.gmane.org/gmane.comp.version-control.git/144642

For pretty formats themselves (and possibly other script-ish bits, like
commit selection), I had experimental patches at one point to embed a
lua interpreter:

  http://thread.gmane.org/gmane.comp.version-control.git/206335

Again, I don't expect you to pick up and run with either of those idea
(but I'd love it if you did!). Just adding to the discussion. :)

> ... although I doubt whether git would ever want to do the equivalent of:
> 
> gcloud compute images list  --format='table[box,title=Images](name:sort=1,family)'
> 
> which will print something like this:

That's neat, though I think I'd really prefer just making it easy to get
the data out of git in a structured way, and then applying some cool
json-formatting script to it. Surely "turn this json into a table" is a
thing that could be solved once for everybody (I don't work with it
enough to know, but maybe "jq" can do that already).


But let's get back to reality for a moment. Here are some patches that
address the issues you brought up above.

  [1/5]: doc/rev-list-options: clarify "commit@{Nth}" for "-g" option
  [2/5]: doc/rev-list-options: explain "-g" output formats
  [3/5]: doc/pretty-formats: describe index/time formats for %gd
  [4/5]: date: document and test "raw-local" mode
  [5/5]: date: add "unix" format

The next step is either:

  - add specific reflog-time-formats, as your patch does

  - add a generic reflog-date placeholder, so you can do:

      git log --date=unix --format='%gT'

    or whatever. That still doesn't give you multiple date types in a
    single invocation, though. It's probably not much code to do so, but
    designing the syntax and supporting existing placeholders would be
    some work.

I'm on the fence, so I'll let you decide how you want to proceed. I can
live with "%gr" and "%gt", as they are at least symmetric with their
author/committer counterparts.

-Peff

[PATCH 1/5] doc/rev-list-options: clarify "commit@{Nth}" for "-g" option

[Jeff King]

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 <peff@peff.net>
---
 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 4f009d4..6720ff3 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`.
-- 
2.9.0.406.g77f030d

[PATCH 2/5] doc/rev-list-options: explain "-g" output formats

[Jeff King]

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>
---
 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 6720ff3..5267ee1 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].
-- 
2.9.0.406.g77f030d

[PATCH 3/5] doc/pretty-formats: describe index/time formats for %gd

[Jeff King]

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 <peff@peff.net>
---
 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 29b19b9..36a300a 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])
-- 
2.9.0.406.g77f030d

[PATCH 4/5] date: document and test "raw-local" mode

[Jeff King]

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,
"--relative". It's vague; do we accept it or not? We do
accept it, but it has no effect (which is a reasonable
outcome).

Signed-off-by: Jeff King <peff@peff.net>
---
 Documentation/rev-list-options.txt | 9 ++++++---
 t/t0006-date.sh                    | 1 +
 2 files changed, 7 insertions(+), 3 deletions(-)

diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
index 5267ee1..a6059d1 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
+`--relative`.
 +
 `--date=local` is an alias for `--date=default-local`.
 +
@@ -746,7 +746,10 @@ 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 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 04ce535..276366e 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"
-- 
2.9.0.406.g77f030d

[PATCH 5/5] date: add "unix" format

[Jeff King]

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 <peff@peff.net>
---
 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 a6059d1..0fa4c8b 100644
--- a/Documentation/rev-list-options.txt
+++ b/Documentation/rev-list-options.txt
@@ -751,6 +751,10 @@ 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=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 1e214bd..1486541 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 f1dc289..ebbf6b7 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 4c7aa9b..a996331 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 276366e..886821d 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"
-- 
2.9.0.406.g77f030d

Re: [PATCH] pretty: add format specifiers: %gr, %gt, %gI, gi

[Theodore Ts'o]

On Mon, Jul 11, 2016 at 01:02:02AM -0400, Jeff King wrote:
> Yeah, I'd have hoped for %gd, as well. One thing I think we should move
> towards in the long run is giving more readable names to our
> placeholders for git-log, the way for-each-ref and cat-file do (but
> keeping the existing ones for compatibility and as a shorthand).
> 
> So ideally the answer in the long run is:
> 
>   %(reflog-ref)@{%(reflog-index)}
> 
> or possibly:
> 
>   %(reflog:index)
> 
> for the whole thing. Or something like that. I haven't thought that hard
> about the exact syntax.

Yes, FWIW, I agree that long term, using % followed by one or two
characters is just a mess, and using some kind of human-readable
format is going to make a lot of sense.  I can imagine a few places
where I might still want to type --format=%at in some kind of ad-hoc
shell command, but in most places, if you're using a complex --format
specifier, it's going either in a shell script or in a .gitconfig
file, where being verbose is probably more of an advantage than a
disadvantage.

>   1. It's half-implemented. Why can we do format X, but not format Y
>      (for that matter, why can you do %ct, but there is no --date format
>      that matches it?). That sort of non-orthogonality ends up
>      frustrating for users and makes git look creaky and poorly thought
>      out.

Git *is* creaky and not thought-out in advance; that's just the nature
of how most successful open source projects grow; might as well be
proud of it.  :-)   As Greg K-H has said: "We believe in evolution, and
not intelligent design."  :-)

> > ... although I doubt whether git would ever want to do the equivalent of:
> > 
> > gcloud compute images list  --format='table[box,title=Images](name:sort=1,family)'
> > 
> > which will print something like this:
> 
> That's neat, though I think I'd really prefer just making it easy to get
> the data out of git in a structured way, and then applying some cool
> json-formatting script to it. Surely "turn this json into a table" is a
> thing that could be solved once for everybody (I don't work with it
> enough to know, but maybe "jq" can do that already).

Oh, agreed.  I used that as over-the-top example of something we
probably wouldn't want to put in the git core.  jq can't, but I'm sure
there must be some JSON tool out there which can.

> But let's get back to reality for a moment. Here are some patches that
> address the issues you brought up above.
> 
>   [1/5]: doc/rev-list-options: clarify "commit@{Nth}" for "-g" option
>   [2/5]: doc/rev-list-options: explain "-g" output formats
>   [3/5]: doc/pretty-formats: describe index/time formats for %gd
>   [4/5]: date: document and test "raw-local" mode
>   [5/5]: date: add "unix" format
> 
> The next step is either:
> 
>   - add specific reflog-time-formats, as your patch does
> 
>   - add a generic reflog-date placeholder, so you can do:
> 
>       git log --date=unix --format='%gT'
> 
>     or whatever. That still doesn't give you multiple date types in a
>     single invocation, though. It's probably not much code to do so, but
>     designing the syntax and supporting existing placeholders would be
>     some work.
> 
> I'm on the fence, so I'll let you decide how you want to proceed. I can
> live with "%gr" and "%gt", as they are at least symmetric with their
> author/committer counterparts.

I'm on the fence myself.  I can live with either, since either way the
long message command line will be going in .gitconfig.  I have a
slight preference for %gr and %gt, as %gT isn't orthogonal with
%ad/%cd, but I could be easily pursuaded otherwise.

Does anyone else have a strong opinion?

						- Ted

Re: [PATCH 3/5] doc/pretty-formats: describe index/time formats for %gd

[Theodore Ts'o]

On Mon, Jul 11, 2016 at 01:05:13AM -0400, Jeff King wrote:
> 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.

Is it worth mentioning that the shortening only happens if the user
specifies a selector with '/' in it in the first place?  I was
confused when I was first playing with these selectors because %gd and
%gD are identical if you run

	git reflog --format=%gd -3 master
	git reflog --format=%gD -3 master

and are only different if you run:

	git reflog --format=%gd -3 refs/heads/master
	git reflog --format=%gD -3 refs/heads/master

					- Ted
					

Re: [PATCH 4/5] date: document and test "raw-local" mode

[Theodore Ts'o]

On Mon, Jul 11, 2016 at 01:06:17AM -0400, Jeff King wrote:
> 
> 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).

Maybe add an editorial statement that in most cases this isn't
particularly useful?  Documenting raw-local implies that someone might
want to consider using it, and it's not clear to me folks should ever
try --- they're more likely to confuse themselves more than anything
else.

					- Ted

Re: [PATCH] pretty: add format specifiers: %gr, %gt, %gI, gi

[Junio C Hamano]

Theodore Ts'o <tytso@mit.edu> writes:

>> I'm on the fence, so I'll let you decide how you want to proceed. I can
>> live with "%gr" and "%gt", as they are at least symmetric with their
>> author/committer counterparts.
>
> I'm on the fence myself.  I can live with either, since either way the
> long message command line will be going in .gitconfig.  I have a
> slight preference for %gr and %gt, as %gT isn't orthogonal with
> %ad/%cd, but I could be easily pursuaded otherwise.
>
> Does anyone else have a strong opinion?

I am fine with %gr/%gt, with the understanding that the step beyond
that would not be to add %gT but to do %(reflog:...), and giving
similar longform to other things like %ad so that we can move things
in the "maybe cumbersome to type but more readable" direction.

Re: [PATCH 3/5] doc/pretty-formats: describe index/time formats for %gd

[Jeff King]

On Mon, Jul 11, 2016 at 12:48:34PM -0400, Theodore Ts'o wrote:

> On Mon, Jul 11, 2016 at 01:05:13AM -0400, Jeff King wrote:
> > 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.
> 
> Is it worth mentioning that the shortening only happens if the user
> specifies a selector with '/' in it in the first place?  I was
> confused when I was first playing with these selectors because %gd and
> %gD are identical if you run
> 
> 	git reflog --format=%gd -3 master
> 	git reflog --format=%gD -3 master
> 
> and are only different if you run:
> 
> 	git reflog --format=%gd -3 refs/heads/master
> 	git reflog --format=%gD -3 refs/heads/master

Yeah, I noticed that "shortened" is not really defined when I was
writing this.

Maybe this on top of the other documentation patches?

-- >8 --
Subject: [PATCH] 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 <peff@peff.net>
---
 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 36a300a..b95d67e 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])
-- 
2.9.0.406.g77f030d

Re: [PATCH 4/5] date: document and test "raw-local" mode

[Jeff King]

On Mon, Jul 11, 2016 at 12:50:00PM -0400, Theodore Ts'o wrote:

> On Mon, Jul 11, 2016 at 01:06:17AM -0400, Jeff King wrote:
> > 
> > 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).
> 
> Maybe add an editorial statement that in most cases this isn't
> particularly useful?  Documenting raw-local implies that someone might
> want to consider using it, and it's not clear to me folks should ever
> try --- they're more likely to confuse themselves more than anything
> else.

I waffled on making such a statement. I agree it's unlikely to be that
useful in practice. The most plausible scenario I could come up with is
a program or script that asks for "--date=raw" because it's going to
format the date later. Somebody using that program may prefer their
local timestamps. Normally you'd just say "--date=iso-local" or whatever
format you prefer, but because this is transiting through the other
program which only understands --date=raw, you have to keep using that
format.

I hoped that the explanation I added would prevent confusion, or at
least be an improvement over the existing documentation of "doesn't
work".

-Peff

Re: [PATCH 3/5] doc/pretty-formats: describe index/time formats for %gd

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> Maybe this on top of the other documentation patches?
>
> -- >8 --
> Subject: [PATCH] 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 <peff@peff.net>
> ---
>  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 36a300a..b95d67e 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`).

Sounds about the right amount of detail to me.  Thanks.

>  - '%gn': reflog identity name
>  - '%gN': reflog identity name (respecting .mailmap, see
>    linkgit:git-shortlog[1] or linkgit:git-blame[1])