[PATCH 0/8] learn the "summary" pretty format

[PATCH 0/8] learn the "summary" pretty format

[Denton Liu]

On this mailing list (and many others) the standard way to reference
other commits with the "summary" format, e.g. "f86a374 ("pack-bitmap.c:
fix a memleak", 2015-03-30)". Since it's so commonly used, let's
standardise it as a pretty format.\n

Denton Liu (8):
  pretty-formats.txt: use generic terms for hash
  revision: make get_revision_mark() return const pointer
  revision: change abbrev_commit_given to abbrev_commit_explicit
  pretty.c: inline initalize format_context
  pretty.c: extract functionality to repo_format_commit_generic()
  reflog-walk.c: don't print last newline with oneline
  pretty: implement 'summary' format
  SubmittingPatches: use `--pretty=summary`

 Documentation/SubmittingPatches    |  6 +++
 Documentation/pretty-formats.txt   | 25 ++++++----
 Documentation/pretty-options.txt   |  2 +-
 Documentation/rev-list-options.txt |  2 +-
 builtin/log.c                      | 30 ++++++++++--
 log-tree.c                         | 15 ++++--
 pretty.c                           | 74 +++++++++++++++++++++++++-----
 pretty.h                           |  1 +
 reflog-walk.c                      |  6 ++-
 revision.c                         |  7 +--
 revision.h                         |  6 +--
 t/t4205-log-pretty-formats.sh      | 52 +++++++++++++++++++++
 12 files changed, 188 insertions(+), 38 deletions(-)

-- 
2.24.0.rc2.262.g2d07a97ef5

[PATCH 1/8] pretty-formats.txt: use generic terms for hash

[Denton Liu]

Since Git is planning on upgrading from SHA-1 to be more hash-agnostic,
replace specific references to SHA-1 with more generic terminology.

Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
 Documentation/pretty-formats.txt | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt
index b87e2e83e6..71eef684d0 100644
--- a/Documentation/pretty-formats.txt
+++ b/Documentation/pretty-formats.txt
@@ -4,7 +4,7 @@ PRETTY FORMATS
 If the commit is a merge, and if the pretty-format
 is not 'oneline', 'email' or 'raw', an additional line is
 inserted before the 'Author:' line.  This line begins with
-"Merge: " and the sha1s of ancestral commits are printed,
+"Merge: " and the hashes of ancestral commits are printed,
 separated by spaces.  Note that the listed commits may not
 necessarily be the list of the *direct* parent commits if you
 have limited your view of history: for example, if you are
@@ -20,20 +20,20 @@ built-in formats:
 
 * 'oneline'
 
-	  <sha1> <title line>
+	  <hash> <title line>
 +
 This is designed to be as compact as possible.
 
 * 'short'
 
-	  commit <sha1>
+	  commit <hash>
 	  Author: <author>
 
 	      <title line>
 
 * 'medium'
 
-	  commit <sha1>
+	  commit <hash>
 	  Author: <author>
 	  Date:   <author date>
 
@@ -43,7 +43,7 @@ This is designed to be as compact as possible.
 
 * 'full'
 
-	  commit <sha1>
+	  commit <hash>
 	  Author: <author>
 	  Commit: <committer>
 
@@ -53,7 +53,7 @@ This is designed to be as compact as possible.
 
 * 'fuller'
 
-	  commit <sha1>
+	  commit <hash>
 	  Author:     <author>
 	  AuthorDate: <author date>
 	  Commit:     <committer>
@@ -65,7 +65,7 @@ This is designed to be as compact as possible.
 
 * 'email'
 
-	  From <sha1> <date>
+	  From <hash> <date>
 	  From: <author>
 	  Date: <author date>
 	  Subject: [PATCH] <title line>
@@ -75,7 +75,7 @@ This is designed to be as compact as possible.
 * 'raw'
 +
 The 'raw' format shows the entire commit exactly as
-stored in the commit object.  Notably, the SHA-1s are
+stored in the commit object.  Notably, the hashes are
 displayed in full, regardless of whether --abbrev or
 --no-abbrev are used, and 'parents' information show the
 true parent commits, without taking grafts or history
-- 
2.24.0.rc2.262.g2d07a97ef5

[PATCH 2/8] revision: make get_revision_mark() return const pointer

[Denton Liu]

get_revision_mark() used to return a `char *`, even though all of the
strings it was returning were string literals. Make get_revision_mark()
return a `const char *` so that callers won't be tempted to modify the
returned string.

Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
 revision.c | 4 ++--
 revision.h | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/revision.c b/revision.c
index 0e39b2b8a5..2151b119b7 100644
--- a/revision.c
+++ b/revision.c
@@ -3944,7 +3944,7 @@ struct commit *get_revision(struct rev_info *revs)
 	return c;
 }
 
-char *get_revision_mark(const struct rev_info *revs, const struct commit *commit)
+const char *get_revision_mark(const struct rev_info *revs, const struct commit *commit)
 {
 	if (commit->object.flags & BOUNDARY)
 		return "-";
@@ -3966,7 +3966,7 @@ char *get_revision_mark(const struct rev_info *revs, const struct commit *commit
 
 void put_revision_mark(const struct rev_info *revs, const struct commit *commit)
 {
-	char *mark = get_revision_mark(revs, commit);
+	const char *mark = get_revision_mark(revs, commit);
 	if (!strlen(mark))
 		return;
 	fputs(mark, stdout);
diff --git a/revision.h b/revision.h
index 4134dc6029..addd69410b 100644
--- a/revision.h
+++ b/revision.h
@@ -322,8 +322,8 @@ int handle_revision_arg(const char *arg, struct rev_info *revs,
 void reset_revision_walk(void);
 int prepare_revision_walk(struct rev_info *revs);
 struct commit *get_revision(struct rev_info *revs);
-char *get_revision_mark(const struct rev_info *revs,
-			const struct commit *commit);
+const char *get_revision_mark(const struct rev_info *revs,
+			      const struct commit *commit);
 void put_revision_mark(const struct rev_info *revs,
 		       const struct commit *commit);
 
-- 
2.24.0.rc2.262.g2d07a97ef5

[PATCH 3/8] revision: change abbrev_commit_given to abbrev_commit_explicit

[Denton Liu]

In a future patch, we want to know if `--[no-]abbrev-commit` arguments
have been explicitly provided. Since `rev_info.abbrev_commit_given` is
only used in one place, co-opt it to become
`rev_info.abbrev_commit_explicit`. This information will be used in a
future patch.

With this change, the semantics of the original usage (in
the `--pretty=raw` codepath) aren't altered.

Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
 builtin/log.c | 2 +-
 revision.c    | 3 ++-
 revision.h    | 2 +-
 3 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/builtin/log.c b/builtin/log.c
index 89873d2dc2..e4df16be79 100644
--- a/builtin/log.c
+++ b/builtin/log.c
@@ -230,7 +230,7 @@ static void cmd_log_init_finish(int argc, const char **argv, const char *prefix,
 		 */
 		if (!decoration_given)
 			decoration_style = 0;
-		if (!rev->abbrev_commit_given)
+		if (!rev->abbrev_commit_explicit)
 			rev->abbrev_commit = 0;
 	}
 
diff --git a/revision.c b/revision.c
index 2151b119b7..02b49ab754 100644
--- a/revision.c
+++ b/revision.c
@@ -2271,9 +2271,10 @@ static int handle_revision_opt(struct rev_info *revs, int argc, const char **arg
 			revs->abbrev = hexsz;
 	} else if (!strcmp(arg, "--abbrev-commit")) {
 		revs->abbrev_commit = 1;
-		revs->abbrev_commit_given = 1;
+		revs->abbrev_commit_explicit = 1;
 	} else if (!strcmp(arg, "--no-abbrev-commit")) {
 		revs->abbrev_commit = 0;
+		revs->abbrev_commit_explicit = 1;
 	} else if (!strcmp(arg, "--full-diff")) {
 		revs->diff = 1;
 		revs->full_diff = 1;
diff --git a/revision.h b/revision.h
index addd69410b..7670f29973 100644
--- a/revision.h
+++ b/revision.h
@@ -185,7 +185,7 @@ struct rev_info {
 			show_signature:1,
 			pretty_given:1,
 			abbrev_commit:1,
-			abbrev_commit_given:1,
+			abbrev_commit_explicit:1,
 			zero_commit:1,
 			use_terminator:1,
 			missing_newline:1,
-- 
2.24.0.rc2.262.g2d07a97ef5

[PATCH 4/8] pretty.c: inline initalize format_context

[Denton Liu]

Instead of memsetting and then initializing the fields in the struct,
move the initialization of `format_context` to its assignment.

In preparation for a future commit where we mechanically move lines from
repo_format_commit_message() into a helper function,
`format_context.wrap_start` is not generically used so move its
assignment closer to its use.

Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
 pretty.c | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/pretty.c b/pretty.c
index b32f036953..6f2b0ad917 100644
--- a/pretty.c
+++ b/pretty.c
@@ -1610,14 +1610,13 @@ void repo_format_commit_message(struct repository *r,
 				const char *format, struct strbuf *sb,
 				const struct pretty_print_context *pretty_ctx)
 {
-	struct format_commit_context context;
+	struct format_commit_context context = {
+		.commit = commit,
+		.pretty_ctx = pretty_ctx
+	};
 	const char *output_enc = pretty_ctx->output_encoding;
 	const char *utf8 = "UTF-8";
 
-	memset(&context, 0, sizeof(context));
-	context.commit = commit;
-	context.pretty_ctx = pretty_ctx;
-	context.wrap_start = sb->len;
 	/*
 	 * convert a commit message to UTF-8 first
 	 * as far as 'format_commit_item' assumes it in UTF-8
@@ -1626,6 +1625,7 @@ void repo_format_commit_message(struct repository *r,
 					       &context.commit_encoding,
 					       utf8);
 
+	context.wrap_start = sb->len;
 	strbuf_expand(sb, format, format_commit_item, &context);
 	rewrap_message_tail(sb, &context, 0, 0, 0);
 
-- 
2.24.0.rc2.262.g2d07a97ef5

[PATCH 5/8] pretty.c: extract functionality to repo_format_commit_generic()

[Denton Liu]

In a future commit, we will be reusing common functionality from
repo_format_commit_message(). Extract this common functionality into
repo_format_commit_generic() so that it can be reused in the future.

Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
 pretty.c | 35 ++++++++++++++++++++++++++++-------
 1 file changed, 28 insertions(+), 7 deletions(-)

diff --git a/pretty.c b/pretty.c
index 6f2b0ad917..a6e5fc115a 100644
--- a/pretty.c
+++ b/pretty.c
@@ -1605,10 +1605,14 @@ void userformat_find_requirements(const char *fmt, struct userformat_want *w)
 	strbuf_release(&dummy);
 }
 
-void repo_format_commit_message(struct repository *r,
-				const struct commit *commit,
-				const char *format, struct strbuf *sb,
-				const struct pretty_print_context *pretty_ctx)
+static void repo_format_commit_generic(struct repository *r,
+				       const struct commit *commit,
+				       struct strbuf *sb,
+				       const struct pretty_print_context *pretty_ctx,
+				       void (*fn)(struct strbuf *,
+						  struct format_commit_context *,
+						  void *),
+				       void *data)
 {
 	struct format_commit_context context = {
 		.commit = commit,
@@ -1625,9 +1629,7 @@ void repo_format_commit_message(struct repository *r,
 					       &context.commit_encoding,
 					       utf8);
 
-	context.wrap_start = sb->len;
-	strbuf_expand(sb, format, format_commit_item, &context);
-	rewrap_message_tail(sb, &context, 0, 0, 0);
+	fn(sb, &context, data);
 
 	/* then convert a commit message to an actual output encoding */
 	if (output_enc) {
@@ -1651,6 +1653,25 @@ void repo_format_commit_message(struct repository *r,
 	repo_unuse_commit_buffer(r, commit, context.message);
 }
 
+static void do_repo_format_commit_message(struct strbuf *sb,
+					  struct format_commit_context *context,
+					  void *data)
+{
+	const char *format = data;
+	context->wrap_start = sb->len;
+	strbuf_expand(sb, format, format_commit_item, context);
+	rewrap_message_tail(sb, context, 0, 0, 0);
+}
+
+void repo_format_commit_message(struct repository *r,
+				const struct commit *commit,
+				const char *format, struct strbuf *sb,
+				const struct pretty_print_context *pretty_ctx)
+{
+	repo_format_commit_generic(r, commit, sb, pretty_ctx,
+				   do_repo_format_commit_message, (void *)format);
+}
+
 static void pp_header(struct pretty_print_context *pp,
 		      const char *encoding,
 		      const struct commit *commit,
-- 
2.24.0.rc2.262.g2d07a97ef5

[PATCH 6/8] reflog-walk.c: don't print last newline with oneline

[Denton Liu]

In a future commit, we want to possibly be able to continue the reflog message on
the same line without breaking the line. As a result, when
`oneline == 1`, strip any trailing new lines.

Add these missing newlines back in show_log().

Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
 log-tree.c    | 4 +++-
 reflog-walk.c | 6 +++++-
 2 files changed, 8 insertions(+), 2 deletions(-)

diff --git a/log-tree.c b/log-tree.c
index 923a299e70..4a7d668af6 100644
--- a/log-tree.c
+++ b/log-tree.c
@@ -661,8 +661,10 @@ void show_log(struct rev_info *opt)
 					    opt->commit_format == CMIT_FMT_ONELINE,
 					    &opt->date_mode,
 					    opt->date_mode_explicit);
-			if (opt->commit_format == CMIT_FMT_ONELINE)
+			if (opt->commit_format == CMIT_FMT_ONELINE) {
+				putc('\n', opt->diffopt.file);
 				return;
+			}
 		}
 	}
 
diff --git a/reflog-walk.c b/reflog-walk.c
index 3a25b27d8f..e2b4c0b290 100644
--- a/reflog-walk.c
+++ b/reflog-walk.c
@@ -285,7 +285,11 @@ void show_reflog_message(struct reflog_walk_info *reflog_info, int oneline,
 		info = &commit_reflog->reflogs->items[commit_reflog->recno+1];
 		get_reflog_selector(&selector, reflog_info, dmode, force_date, 0);
 		if (oneline) {
-			printf("%s: %s", selector.buf, info->message);
+			struct strbuf message = STRBUF_INIT;
+			strbuf_addstr(&message, info->message);
+			strbuf_trim_trailing_newline(&message);
+			printf("%s: %s", selector.buf, message.buf);
+			strbuf_release(&message);
 		}
 		else {
 			printf("Reflog: %s (%s)\nReflog message: %s",
-- 
2.24.0.rc2.262.g2d07a97ef5

[PATCH 7/8] pretty: implement 'summary' format

[Denton Liu]

The standard format for referencing other commits within some projects
(such as git.git) is the summary format. This is described in
Documentation/SubmittingPatches as

	If you want to reference a previous commit in the history of a stable
	branch, use the format "abbreviated sha1 (subject, date)",
	with the subject enclosed in a pair of double-quotes, like this:

	....
		Commit f86a374 ("pack-bitmap.c: fix a memleak", 2015-03-30)
		noticed that ...
	....

Since this format is so commonly used, standardize it as a pretty
format.

This format is implemented as a separate flow that skips most of
pretty_print_commit() and instead calls format_commit_summary(). The
reason why this is done is because the other pretty formats expect
output to be generated in a specific order. Specifically, the header,
including the date, is always printed before the commit message,
including the subject. Reversing the order would be possible but would
involve butchering pretty_print_commit() so it is implemented as a
separate flow.

Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
 Documentation/pretty-formats.txt   |  9 ++++++
 Documentation/pretty-options.txt   |  2 +-
 Documentation/rev-list-options.txt |  2 +-
 builtin/log.c                      | 30 ++++++++++++++---
 log-tree.c                         | 11 +++++--
 pretty.c                           | 31 +++++++++++++++++-
 pretty.h                           |  1 +
 t/t4205-log-pretty-formats.sh      | 52 ++++++++++++++++++++++++++++++
 8 files changed, 127 insertions(+), 11 deletions(-)

diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt
index 71eef684d0..5641903b93 100644
--- a/Documentation/pretty-formats.txt
+++ b/Documentation/pretty-formats.txt
@@ -63,6 +63,15 @@ This is designed to be as compact as possible.
 
 	       <full commit message>
 
+* 'summary'
+
+	  <abbrev hash> ("<title line>", <short author date>)
++
+This format is useful for referring to other commits when writing a new
+commit message. Although by default, '<abbrev sha1>' is used, this can
+be overridden with '--no-abbrev'. In addition, '<short author date>' can
+be overridden by with '--date='.
+
 * 'email'
 
 	  From <hash> <date>
diff --git a/Documentation/pretty-options.txt b/Documentation/pretty-options.txt
index e44fc8f738..0a5b206193 100644
--- a/Documentation/pretty-options.txt
+++ b/Documentation/pretty-options.txt
@@ -3,7 +3,7 @@
 
 	Pretty-print the contents of the commit logs in a given format,
 	where '<format>' can be one of 'oneline', 'short', 'medium',
-	'full', 'fuller', 'email', 'raw', 'format:<string>'
+	'full', 'fuller', 'summary', 'email', 'raw', 'format:<string>'
 	and 'tformat:<string>'.  When '<format>' is none of the above,
 	and has '%placeholder' in it, it acts as if
 	'--pretty=tformat:<format>' were given.
diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
index 90ff9e2bea..76df494ed6 100644
--- a/Documentation/rev-list-options.txt
+++ b/Documentation/rev-list-options.txt
@@ -289,7 +289,7 @@ depending on a few rules:
 4. Otherwise, show the index format.
 --
 +
-Under `--pretty=oneline`, the commit message is
+Under `--pretty=oneline` and `--pretty=summary`, 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].
diff --git a/builtin/log.c b/builtin/log.c
index e4df16be79..ad96a746a3 100644
--- a/builtin/log.c
+++ b/builtin/log.c
@@ -223,15 +223,35 @@ static void cmd_log_init_finish(int argc, const char **argv, const char *prefix,
 		read_mailmap(rev->mailmap, NULL);
 	}
 
-	if (rev->pretty_given && rev->commit_format == CMIT_FMT_RAW) {
+	if (rev->pretty_given) {
+		switch (rev->commit_format) {
+
 		/*
 		 * "log --pretty=raw" is special; ignore UI oriented
 		 * configuration variables such as decoration.
 		 */
-		if (!decoration_given)
-			decoration_style = 0;
-		if (!rev->abbrev_commit_explicit)
-			rev->abbrev_commit = 0;
+		case CMIT_FMT_RAW:
+			if (!decoration_given)
+				decoration_style = 0;
+			if (!rev->abbrev_commit_explicit)
+				rev->abbrev_commit = 0;
+			break;
+
+		/*
+		 * "log --pretty=summary" is special; ignore UI oriented
+		 * configuration variables such as decoration but keep
+		 * abbreviations.
+		 */
+		case CMIT_FMT_SUMMARY:
+			if (!decoration_given)
+				decoration_style = 0;
+			if (!rev->abbrev_commit_explicit)
+				rev->abbrev_commit = 1;
+			break;
+
+		default:
+			break;
+		}
 	}
 
 	if (decoration_style) {
diff --git a/log-tree.c b/log-tree.c
index 4a7d668af6..433adaf0f1 100644
--- a/log-tree.c
+++ b/log-tree.c
@@ -627,7 +627,8 @@ void show_log(struct rev_info *opt)
 		ctx.print_email_subject = 1;
 	} else if (opt->commit_format != CMIT_FMT_USERFORMAT) {
 		fputs(diff_get_color_opt(&opt->diffopt, DIFF_COMMIT), opt->diffopt.file);
-		if (opt->commit_format != CMIT_FMT_ONELINE)
+		if (opt->commit_format != CMIT_FMT_ONELINE &&
+		    opt->commit_format != CMIT_FMT_SUMMARY)
 			fputs("commit ", opt->diffopt.file);
 
 		if (!opt->graph)
@@ -644,7 +645,8 @@ void show_log(struct rev_info *opt)
 			       find_unique_abbrev(&parent->object.oid, abbrev_commit));
 		fputs(diff_get_color_opt(&opt->diffopt, DIFF_RESET), opt->diffopt.file);
 		show_decorations(opt, commit);
-		if (opt->commit_format == CMIT_FMT_ONELINE) {
+		if (opt->commit_format == CMIT_FMT_ONELINE ||
+		    opt->commit_format == CMIT_FMT_SUMMARY) {
 			putc(' ', opt->diffopt.file);
 		} else {
 			putc('\n', opt->diffopt.file);
@@ -658,12 +660,15 @@ void show_log(struct rev_info *opt)
 			 * graph info here.
 			 */
 			show_reflog_message(opt->reflog_info,
-					    opt->commit_format == CMIT_FMT_ONELINE,
+					    (opt->commit_format == CMIT_FMT_ONELINE ||
+					     opt->commit_format == CMIT_FMT_SUMMARY),
 					    &opt->date_mode,
 					    opt->date_mode_explicit);
 			if (opt->commit_format == CMIT_FMT_ONELINE) {
 				putc('\n', opt->diffopt.file);
 				return;
+			} else if (opt->commit_format == CMIT_FMT_SUMMARY) {
+				putc(' ', opt->diffopt.file);
 			}
 		}
 	}
diff --git a/pretty.c b/pretty.c
index a6e5fc115a..8efb2486a5 100644
--- a/pretty.c
+++ b/pretty.c
@@ -97,7 +97,8 @@ static void setup_commit_formats(void)
 		{ "mboxrd",	CMIT_FMT_MBOXRD,	0,	0 },
 		{ "fuller",	CMIT_FMT_FULLER,	0,	8 },
 		{ "full",	CMIT_FMT_FULL,		0,	8 },
-		{ "oneline",	CMIT_FMT_ONELINE,	1,	0 }
+		{ "oneline",	CMIT_FMT_ONELINE,	1,	0 },
+		{ "summary",	CMIT_FMT_SUMMARY,	1,	0 },
 		/*
 		 * Please update $__git_log_pretty_formats in
 		 * git-completion.bash when you add new formats.
@@ -1672,6 +1673,26 @@ void repo_format_commit_message(struct repository *r,
 				   do_repo_format_commit_message, (void *)format);
 }
 
+static void do_repo_format_commit_summary(struct strbuf *sb,
+					  struct format_commit_context *context,
+					  void *additional_context)
+{
+	struct ident_split ident;
+
+	parse_commit_header(context);
+	parse_commit_message(context);
+
+	strbuf_addstr(sb, "(\"");
+	format_subject(sb, context->message + context->subject_off, " ");
+	if (!split_ident_line(&ident,
+			      context->message + context->author.off,
+			      context->author.len)) {
+		strbuf_addstr(sb, "\", ");
+		strbuf_addstr(sb, show_ident_date(&ident, &context->pretty_ctx->date_mode));
+	}
+	strbuf_addstr(sb, ")");
+}
+
 static void pp_header(struct pretty_print_context *pp,
 		      const char *encoding,
 		      const struct commit *commit,
@@ -1923,6 +1944,14 @@ void pretty_print_commit(struct pretty_print_context *pp,
 		format_commit_message(commit, user_format, sb, pp);
 		return;
 	}
+	if (pp->fmt == CMIT_FMT_SUMMARY) {
+		if (!pp->date_mode_explicit)
+			pp->date_mode = *DATE_MODE(SHORT);
+
+		repo_format_commit_generic(the_repository, commit, sb, pp,
+					   do_repo_format_commit_summary, NULL);
+		return;
+	}
 
 	encoding = get_log_output_encoding();
 	msg = reencoded = logmsg_reencode(commit, NULL, encoding);
diff --git a/pretty.h b/pretty.h
index 4ad1fc31ff..6d5b18a4f1 100644
--- a/pretty.h
+++ b/pretty.h
@@ -16,6 +16,7 @@ enum cmit_fmt {
 	CMIT_FMT_FULL,
 	CMIT_FMT_FULLER,
 	CMIT_FMT_ONELINE,
+	CMIT_FMT_SUMMARY,
 	CMIT_FMT_EMAIL,
 	CMIT_FMT_MBOXRD,
 	CMIT_FMT_USERFORMAT,
diff --git a/t/t4205-log-pretty-formats.sh b/t/t4205-log-pretty-formats.sh
index f42a69faa2..09b1a33cf1 100755
--- a/t/t4205-log-pretty-formats.sh
+++ b/t/t4205-log-pretty-formats.sh
@@ -788,4 +788,56 @@ test_expect_success '%S in git log --format works with other placeholders (part
 	test_cmp expect actual
 '
 
+test_expect_success 'log --pretty=summary' '
+	git log --date=short --pretty="tformat:%h (\"%s\", %ad)" >expect &&
+	git log --pretty=summary >actual &&
+	test_cmp expect actual
+'
+
+test_expect_success 'log --pretty=summary with log.date is overridden by short date' '
+	git log --date=short --pretty="tformat:%h (\"%s\", %ad)" >expect &&
+	test_config log.date rfc &&
+	git log --pretty=summary >actual &&
+	test_cmp expect actual
+'
+
+test_expect_success 'log --pretty=summary with explicit date overrides short date' '
+	git log --date=rfc --pretty="tformat:%h (\"%s\", %ad)" >expect &&
+	git log --date=rfc --pretty=summary >actual &&
+	test_cmp expect actual
+'
+
+test_expect_success 'log --pretty=summary with log.abbrevCommit is overidden' '
+	git log --date=short --pretty="tformat:%h (\"%s\", %ad)" >expect &&
+	test_config log.abbrevCommit false &&
+	git log --pretty=summary >actual &&
+	test_cmp expect actual
+'
+
+test_expect_success 'log --pretty=summary with explicit --no-abbrev overrides abbreviated' '
+	git log --date=short --pretty="tformat:%H (\"%s\", %ad)" >expect &&
+	git log --no-abbrev --pretty=summary >actual &&
+	test_cmp expect actual
+'
+
+test_expect_success 'log --pretty=summary with log.decorate is overridden' '
+	git log --date=short --pretty="tformat:%h (\"%s\", %ad)" >expect &&
+	test_config log.decorate short &&
+	git log --pretty=summary >actual &&
+	test_cmp expect actual
+'
+
+test_expect_success 'log --pretty=summary with explicit decorate overrides no decoration' '
+	git log --date=short --pretty="tformat:%h%d (\"%s\", %ad)" >expect &&
+	git log --decorate=short --pretty=summary >actual &&
+	test_cmp expect actual
+'
+
+test_expect_success 'log --pretty=summary with --walk-reflogs' '
+	test_config log.date short &&
+	git log --walk-reflogs --pretty="tformat:%h %gd: %gs (\"%s\", %ad)" >expect &&
+	git log --walk-reflogs --pretty=summary >actual &&
+	test_cmp expect actual
+'
+
 test_done
-- 
2.24.0.rc2.262.g2d07a97ef5

[PATCH 8/8] SubmittingPatches: use `--pretty=summary`

[Denton Liu]

Since Git was taught the `--pretty=summary` option, it is no longer
necessary to manually specify the format string to get the commit
summary. Teach users to use the new option while keeping the old
invocation around in case they have an older version of Git.

Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
 Documentation/SubmittingPatches | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 1a60cc1329..6969ecca45 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -153,6 +153,12 @@ with the subject enclosed in a pair of double-quotes, like this:
 The "Copy commit summary" command of gitk can be used to obtain this
 format, or this invocation of `git show`:
 
+....
+	git show -s --pretty=summary <commit>
+....
+
+or, on an older version of Git without support for --pretty=summary:
+
 ....
 	git show -s --date=short --pretty='format:%h ("%s", %ad)' <commit>
 ....
-- 
2.24.0.rc2.262.g2d07a97ef5

Re: [PATCH 7/8] pretty: implement 'summary' format

[Eric Sunshine]

On Mon, Nov 4, 2019 at 3:04 PM Denton Liu <liu.denton@gmail.com> wrote:
> diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt
> @@ -63,6 +63,15 @@ This is designed to be as compact as possible.
> +* 'summary'
> +
> +         <abbrev hash> ("<title line>", <short author date>)
> ++
> +This format is useful for referring to other commits when writing a new
> +commit message. Although by default, '<abbrev sha1>' is used, this can

Why does this talk about "sha1" when patch 1/8 removed references to
SHA-1 in favor of generic "hashes"?

> +be overridden with '--no-abbrev'. In addition, '<short author date>' can
> +be overridden by with '--date='.

Re: [PATCH 7/8] pretty: implement 'summary' format

[Denton Liu]

Hi Eric,

On Mon, Nov 04, 2019 at 03:16:56PM -0500, Eric Sunshine wrote:
> On Mon, Nov 4, 2019 at 3:04 PM Denton Liu <liu.denton@gmail.com> wrote:
> > diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt
> > @@ -63,6 +63,15 @@ This is designed to be as compact as possible.
> > +* 'summary'
> > +
> > +         <abbrev hash> ("<title line>", <short author date>)
> > ++
> > +This format is useful for referring to other commits when writing a new
> > +commit message. Although by default, '<abbrev sha1>' is used, this can
> 
> Why does this talk about "sha1" when patch 1/8 removed references to
> SHA-1 in favor of generic "hashes"?

Good catch. 1/8 modified pretty-formats.txt but this message references
the content in SubmittingPatches.

In a future reroll, I'll submit a similar patch as 1/8 but targeting
SubmittingPatches instead.

Thanks,

Denton

> 
> > +be overridden with '--no-abbrev'. In addition, '<short author date>' can
> > +be overridden by with '--date='.

Re: [PATCH 7/8] pretty: implement 'summary' format

[Eric Sunshine]

On Mon, Nov 4, 2019 at 3:36 PM Denton Liu <liu.denton@gmail.com> wrote:
> On Mon, Nov 04, 2019 at 03:16:56PM -0500, Eric Sunshine wrote:
> > On Mon, Nov 4, 2019 at 3:04 PM Denton Liu <liu.denton@gmail.com> wrote:
> > > diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt
> > > @@ -63,6 +63,15 @@ This is designed to be as compact as possible.
> > > +* 'summary'
> > > +
> > > +         <abbrev hash> ("<title line>", <short author date>)
> > > ++
> > > +This format is useful for referring to other commits when writing a new
> > > +commit message. Although by default, '<abbrev sha1>' is used, this can
> >
> > Why does this talk about "sha1" when patch 1/8 removed references to
> > SHA-1 in favor of generic "hashes"?
>
> Good catch. 1/8 modified pretty-formats.txt but this message references
> the content in SubmittingPatches.

I'm not sure what you mean. This change is touching
pretty-formats.txt, not SubmittingPatches.

Re: [PATCH 7/8] pretty: implement 'summary' format

[Denton Liu]

On Mon, Nov 04, 2019 at 03:38:54PM -0500, Eric Sunshine wrote:
> On Mon, Nov 4, 2019 at 3:36 PM Denton Liu <liu.denton@gmail.com> wrote:
> > On Mon, Nov 04, 2019 at 03:16:56PM -0500, Eric Sunshine wrote:
> > > On Mon, Nov 4, 2019 at 3:04 PM Denton Liu <liu.denton@gmail.com> wrote:
> > > > diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt
> > > > @@ -63,6 +63,15 @@ This is designed to be as compact as possible.
> > > > +* 'summary'
> > > > +
> > > > +         <abbrev hash> ("<title line>", <short author date>)
> > > > ++
> > > > +This format is useful for referring to other commits when writing a new
> > > > +commit message. Although by default, '<abbrev sha1>' is used, this can
> > >
> > > Why does this talk about "sha1" when patch 1/8 removed references to
> > > SHA-1 in favor of generic "hashes"?
> >
> > Good catch. 1/8 modified pretty-formats.txt but this message references
> > the content in SubmittingPatches.
> 
> I'm not sure what you mean. This change is touching
> pretty-formats.txt, not SubmittingPatches.

My mistake, you were referring to the patch text which is also indeed
incorrect. I skimmed your message too quickly and I thought you were
referring to the commit message which also references "sha1" but in the
context of SubmittingPatches.

Re: [PATCH 6/8] reflog-walk.c: don't print last newline with oneline

[Junio C Hamano]

Denton Liu <liu.denton@gmail.com> writes:

> Subject: Re: [PATCH 6/8] reflog-walk.c: don't print last newline with oneline

Please find a better phrasing that does not mislead the readers to
think "eek, so now output from 'git log -g --oneline' does not get
LF terminated?"

I think you are just changing the place where the LF is given from
the callee that shows a single record (and then used to show LF
after the record) to the caller that calls the callee (and now it
shows LF after the call returns), in order to preserve the output,
but with the given proposed log message, it is not clear if that is
what you meant to do (I can read from the code what _is_ going on,
but the log is to record what you _wanted_ to do, which can be
different).

> @@ -661,8 +661,10 @@ void show_log(struct rev_info *opt)

In the pre-context before this line there is a guard to ensure that
we do this only when showing an entry from the reflog, so the effect
of this hunk is "when showing from reflog in --oneline format, show
LF after showing a single record" ...

>  					    opt->commit_format == CMIT_FMT_ONELINE,
>  					    &opt->date_mode,
>  					    opt->date_mode_explicit);
> -			if (opt->commit_format == CMIT_FMT_ONELINE)
> +			if (opt->commit_format == CMIT_FMT_ONELINE) {
> +				putc('\n', opt->diffopt.file);
>  				return;
> +			}
>  		}
>  	}
>  
> diff --git a/reflog-walk.c b/reflog-walk.c
> index 3a25b27d8f..e2b4c0b290 100644
> --- a/reflog-walk.c
> +++ b/reflog-walk.c
> @@ -285,7 +285,11 @@ void show_reflog_message(struct reflog_walk_info *reflog_info, int oneline,
>  		info = &commit_reflog->reflogs->items[commit_reflog->recno+1];
>  		get_reflog_selector(&selector, reflog_info, dmode, force_date, 0);
>  		if (oneline) {
> -			printf("%s: %s", selector.buf, info->message);
> +			struct strbuf message = STRBUF_INIT;
> +			strbuf_addstr(&message, info->message);
> +			strbuf_trim_trailing_newline(&message);
> +			printf("%s: %s", selector.buf, message.buf);
> +			strbuf_release(&message);

... and this one is what gets called from the above caller; we lost
the final LF (if there is) from the output, that is compensated by
the caller.

How well do we work with the "-z" output format, by the way, with
the hardcoded '\n' on the output codepath?

Making a new allocation feels inefficient just to omit the trailing
newlines.  I wonder if a helper function that takes a "const char *"
and returns a "const char *" in that string that points at the CRLF
or LF or NUL at its end would be warranted.  If we do not care about
CRLF, this part would become something like...

	if (oneline) {
		const char *endp = strchrnul(info->message, '\n');
		printf("%s: %.*s", selector.buf,
			(int)(endp - info->message), info->message);
	}

but I didn't trace the code/data flow to see where info->message
comes from well enough to tell if we need to worry about CRLF.  I
thought reflogs are always written with LF termination, though.

Thanks.

Re: [PATCH 6/8] reflog-walk.c: don't print last newline with oneline

[Denton Liu]

Hi Junio,

On Wed, Nov 06, 2019 at 02:12:17PM +0900, Junio C Hamano wrote:
> Denton Liu <liu.denton@gmail.com> writes:
> 
> > Subject: Re: [PATCH 6/8] reflog-walk.c: don't print last newline with oneline
> 
> Please find a better phrasing that does not mislead the readers to
> think "eek, so now output from 'git log -g --oneline' does not get
> LF terminated?"
> 
> I think you are just changing the place where the LF is given from
> the callee that shows a single record (and then used to show LF
> after the record) to the caller that calls the callee (and now it
> shows LF after the call returns), in order to preserve the output,
> but with the given proposed log message, it is not clear if that is
> what you meant to do (I can read from the code what _is_ going on,
> but the log is to record what you _wanted_ to do, which can be
> different).

Yep, I'll reword the subject line.

> 
> > @@ -661,8 +661,10 @@ void show_log(struct rev_info *opt)
> 
> In the pre-context before this line there is a guard to ensure that
> we do this only when showing an entry from the reflog, so the effect
> of this hunk is "when showing from reflog in --oneline format, show
> LF after showing a single record" ...
> 
> >  					    opt->commit_format == CMIT_FMT_ONELINE,
> >  					    &opt->date_mode,
> >  					    opt->date_mode_explicit);
> > -			if (opt->commit_format == CMIT_FMT_ONELINE)
> > +			if (opt->commit_format == CMIT_FMT_ONELINE) {
> > +				putc('\n', opt->diffopt.file);
> >  				return;
> > +			}
> >  		}
> >  	}
> >  
> > diff --git a/reflog-walk.c b/reflog-walk.c
> > index 3a25b27d8f..e2b4c0b290 100644
> > --- a/reflog-walk.c
> > +++ b/reflog-walk.c
> > @@ -285,7 +285,11 @@ void show_reflog_message(struct reflog_walk_info *reflog_info, int oneline,
> >  		info = &commit_reflog->reflogs->items[commit_reflog->recno+1];
> >  		get_reflog_selector(&selector, reflog_info, dmode, force_date, 0);
> >  		if (oneline) {
> > -			printf("%s: %s", selector.buf, info->message);
> > +			struct strbuf message = STRBUF_INIT;
> > +			strbuf_addstr(&message, info->message);
> > +			strbuf_trim_trailing_newline(&message);
> > +			printf("%s: %s", selector.buf, message.buf);
> > +			strbuf_release(&message);
> 
> ... and this one is what gets called from the above caller; we lost
> the final LF (if there is) from the output, that is compensated by
> the caller.

Yep, thats correct.

> 
> How well do we work with the "-z" output format, by the way, with
> the hardcoded '\n' on the output codepath?

From my tests, `-z` plays well with my changes. I'll add some tests to
be sure, though.

> 
> Making a new allocation feels inefficient just to omit the trailing
> newlines.  I wonder if a helper function that takes a "const char *"
> and returns a "const char *" in that string that points at the CRLF
> or LF or NUL at its end would be warranted.  If we do not care about
> CRLF, this part would become something like...
> 
> 	if (oneline) {
> 		const char *endp = strchrnul(info->message, '\n');
> 		printf("%s: %.*s", selector.buf,
> 			(int)(endp - info->message), info->message);
> 	}

Yep, I think that this works. In fact, we can probably just do

 	if (oneline) {
 		const char *endp = strchrnul(info->message, '\n');
		int len = strlen(info->message);
		if (len > 0)
			len--;
 		printf("%s: %.*s", selector.buf,
 			len, info->message);
 	}

because...

> but I didn't trace the code/data flow to see where info->message
> comes from well enough to tell if we need to worry about CRLF.  I
> thought reflogs are always written with LF termination, though.

I think that you are right. Reflogs are always written with LF
termination. This can be seen in get_reflog_message():

	void get_reflog_message(struct strbuf *sb,
				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;

		info = &commit_reflog->reflogs->items[commit_reflog->recno+1];
		len = strlen(info->message);
		if (len > 0)
=>			len--; /* strip away trailing newline */
		strbuf_add(sb, info->message, len);
	}

> 
> Thanks.

[PATCH v2 00/10] learn the "summary" pretty format

[Denton Liu]

On this mailing list (and many others) the standard way to reference
other commits with the "summary" format, e.g. "f86a374 ("pack-bitmap.c:
fix a memleak", 2015-03-30)". Since it's so commonly used, let's
standardise it as a pretty format.

Changes since v1:

* Replace more references to "sha1" with "hash"

* Clean up 8/10 by losing the allocation and making the subject less
  misleading

* Add tests in 7/10 to ensure 8/10 does not change any behaviour

Denton Liu (10):
  SubmittingPatches: use generic terms for hash
  pretty-formats.txt: use generic terms for hash
  revision: make get_revision_mark() return const pointer
  revision: change abbrev_commit_given to abbrev_commit_explicit
  pretty.c: inline initalize format_context
  pretty.c: extract functionality to repo_format_commit_generic()
  t4205: cover `git log --reflog -z` blindspot
  reflog-walk.c: move where the newline is added
  pretty: implement 'summary' format
  SubmittingPatches: use `--pretty=summary`

 Documentation/SubmittingPatches    |  8 ++-
 Documentation/pretty-formats.txt   | 25 ++++++---
 Documentation/pretty-options.txt   |  2 +-
 Documentation/rev-list-options.txt |  2 +-
 builtin/log.c                      | 30 ++++++++--
 log-tree.c                         | 15 +++--
 pretty.c                           | 74 ++++++++++++++++++++----
 pretty.h                           |  1 +
 reflog-walk.c                      |  8 ++-
 revision.c                         |  7 ++-
 revision.h                         |  6 +-
 t/t4205-log-pretty-formats.sh      | 90 ++++++++++++++++++++++++++++++
 12 files changed, 227 insertions(+), 41 deletions(-)

Range-diff against v1:
 -:  ---------- >  1:  b34e9aea56 SubmittingPatches: use generic terms for hash
 1:  dc88d700b8 =  2:  922cc6d849 pretty-formats.txt: use generic terms for hash
 2:  9d30c287fa =  3:  b31cffd5ef revision: make get_revision_mark() return const pointer
 3:  9ea8d676f7 =  4:  b970e52b57 revision: change abbrev_commit_given to abbrev_commit_explicit
 4:  21809581df =  5:  a2e90c78e6 pretty.c: inline initalize format_context
 5:  7f3a3b5828 =  6:  fd2bbcd169 pretty.c: extract functionality to repo_format_commit_generic()
 -:  ---------- >  7:  b5950823ce t4205: cover `git log --reflog -z` blindspot
 6:  004164c781 !  8:  05dc446d41 reflog-walk.c: don't print last newline with oneline
    @@ Metadata
     Author: Denton Liu <liu.denton@gmail.com>
     
      ## Commit message ##
    -    reflog-walk.c: don't print last newline with oneline
    +    reflog-walk.c: move where the newline is added
     
         In a future commit, we want to possibly be able to continue the reflog message on
         the same line without breaking the line. As a result, when
    @@ Commit message
     
         Add these missing newlines back in show_log().
     
    +    While we're at it, cuddle the else with the closing brace of the if to
    +    more closely match the existing style.
    +
         Signed-off-by: Denton Liu <liu.denton@gmail.com>
     
      ## log-tree.c ##
    @@ reflog-walk.c: void show_reflog_message(struct reflog_walk_info *reflog_info, in
      		get_reflog_selector(&selector, reflog_info, dmode, force_date, 0);
      		if (oneline) {
     -			printf("%s: %s", selector.buf, info->message);
    -+			struct strbuf message = STRBUF_INIT;
    -+			strbuf_addstr(&message, info->message);
    -+			strbuf_trim_trailing_newline(&message);
    -+			printf("%s: %s", selector.buf, message.buf);
    -+			strbuf_release(&message);
    - 		}
    - 		else {
    +-		}
    +-		else {
    ++			int len = strlen(info->message);
    ++			if (len > 0)
    ++				len--; /* strip away trailing newline */
    ++			printf("%s: %.*s", selector.buf, len, info->message);
    ++		} else {
      			printf("Reflog: %s (%s)\nReflog message: %s",
    + 			       selector.buf, info->email, info->message);
    + 		}
 7:  1e280b968c !  9:  e74eab6d21 pretty: implement 'summary' format
    @@ Commit message
         Documentation/SubmittingPatches as
     
                 If you want to reference a previous commit in the history of a stable
    -            branch, use the format "abbreviated sha1 (subject, date)",
    +            branch, use the format "abbreviated hash (subject, date)",
                 with the subject enclosed in a pair of double-quotes, like this:
     
                 ....
    @@ Documentation/pretty-formats.txt: This is designed to be as compact as possible.
     +	  <abbrev hash> ("<title line>", <short author date>)
     ++
     +This format is useful for referring to other commits when writing a new
    -+commit message. Although by default, '<abbrev sha1>' is used, this can
    ++commit message. Although by default, '<abbrev hash>' is used, this can
     +be overridden with '--no-abbrev'. In addition, '<short author date>' can
     +be overridden by with '--date='.
     +
    @@ pretty.h: enum cmit_fmt {
      	CMIT_FMT_USERFORMAT,
     
      ## t/t4205-log-pretty-formats.sh ##
    +@@ t/t4205-log-pretty-formats.sh: do
    + 	'
    + done
    + 
    +-test_expect_success 'NUL termination with --reflog --pretty=oneline' '
    +-	>expect &&
    +-	revs="$(git rev-list --reflog)" &&
    +-	for r in $revs
    +-	do
    +-		# trim trailing newline
    +-		output="$(git show -s --pretty=oneline "$r")" || return 1
    +-		printf "%s" "$output" >>expect
    +-		emit_nul >>expect
    +-	done &&
    +-	git log -z --pretty=oneline --reflog >actual &&
    +-	# no trailing NUL
    +-	test_cmp expect actual
    +-'
    ++for p in oneline summary
    ++do
    ++	test_expect_success "NUL termination with --reflog --pretty=$p" '
    ++		>expect &&
    ++		revs="$(git rev-list --reflog)" &&
    ++		for r in $revs
    ++		do
    ++			# trim trailing newline
    ++			output="$(git show -s --pretty='$p' "$r")" || return 1
    ++			printf "%s" "$output" >>expect
    ++			emit_nul >>expect
    ++		done &&
    ++		git log -z --pretty='$p' --reflog >actual &&
    ++		# no trailing NUL
    ++		test_cmp expect actual
    ++	'
    ++done
    + 
    + test_expect_success 'setup more commits' '
    + 	test_commit "message one" one one message-one &&
     @@ t/t4205-log-pretty-formats.sh: test_expect_success '%S in git log --format works with other placeholders (part
      	test_cmp expect actual
      '
 8:  80e7c4fc66 = 10:  3aaa7a318b SubmittingPatches: use `--pretty=summary`
-- 
2.24.0.298.g3e88fbd976

[PATCH v2 01/10] SubmittingPatches: use generic terms for hash

[Denton Liu]

Since Git is planning on upgrading from SHA-1 to be more hash-agnostic,
replace specific references to SHA-1 with more generic terminology.

Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
 Documentation/SubmittingPatches | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 1a60cc1329..bb7e33ce15 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -142,7 +142,7 @@ archive, summarize the relevant points of the discussion.
 
 [[commit-reference]]
 If you want to reference a previous commit in the history of a stable
-branch, use the format "abbreviated sha1 (subject, date)",
+branch, use the format "abbreviated hash (subject, date)",
 with the subject enclosed in a pair of double-quotes, like this:
 
 ....
-- 
2.24.0.298.g3e88fbd976

[PATCH v2 02/10] pretty-formats.txt: use generic terms for hash

[Denton Liu]

Since Git is planning on upgrading from SHA-1 to be more hash-agnostic,
replace specific references to SHA-1 with more generic terminology.

Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
 Documentation/pretty-formats.txt | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt
index b87e2e83e6..71eef684d0 100644
--- a/Documentation/pretty-formats.txt
+++ b/Documentation/pretty-formats.txt
@@ -4,7 +4,7 @@ PRETTY FORMATS
 If the commit is a merge, and if the pretty-format
 is not 'oneline', 'email' or 'raw', an additional line is
 inserted before the 'Author:' line.  This line begins with
-"Merge: " and the sha1s of ancestral commits are printed,
+"Merge: " and the hashes of ancestral commits are printed,
 separated by spaces.  Note that the listed commits may not
 necessarily be the list of the *direct* parent commits if you
 have limited your view of history: for example, if you are
@@ -20,20 +20,20 @@ built-in formats:
 
 * 'oneline'
 
-	  <sha1> <title line>
+	  <hash> <title line>
 +
 This is designed to be as compact as possible.
 
 * 'short'
 
-	  commit <sha1>
+	  commit <hash>
 	  Author: <author>
 
 	      <title line>
 
 * 'medium'
 
-	  commit <sha1>
+	  commit <hash>
 	  Author: <author>
 	  Date:   <author date>
 
@@ -43,7 +43,7 @@ This is designed to be as compact as possible.
 
 * 'full'
 
-	  commit <sha1>
+	  commit <hash>
 	  Author: <author>
 	  Commit: <committer>
 
@@ -53,7 +53,7 @@ This is designed to be as compact as possible.
 
 * 'fuller'
 
-	  commit <sha1>
+	  commit <hash>
 	  Author:     <author>
 	  AuthorDate: <author date>
 	  Commit:     <committer>
@@ -65,7 +65,7 @@ This is designed to be as compact as possible.
 
 * 'email'
 
-	  From <sha1> <date>
+	  From <hash> <date>
 	  From: <author>
 	  Date: <author date>
 	  Subject: [PATCH] <title line>
@@ -75,7 +75,7 @@ This is designed to be as compact as possible.
 * 'raw'
 +
 The 'raw' format shows the entire commit exactly as
-stored in the commit object.  Notably, the SHA-1s are
+stored in the commit object.  Notably, the hashes are
 displayed in full, regardless of whether --abbrev or
 --no-abbrev are used, and 'parents' information show the
 true parent commits, without taking grafts or history
-- 
2.24.0.298.g3e88fbd976

[PATCH v2 03/10] revision: make get_revision_mark() return const pointer

[Denton Liu]

get_revision_mark() used to return a `char *`, even though all of the
strings it was returning were string literals. Make get_revision_mark()
return a `const char *` so that callers won't be tempted to modify the
returned string.

Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
 revision.c | 4 ++--
 revision.h | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/revision.c b/revision.c
index 0e39b2b8a5..2151b119b7 100644
--- a/revision.c
+++ b/revision.c
@@ -3944,7 +3944,7 @@ struct commit *get_revision(struct rev_info *revs)
 	return c;
 }
 
-char *get_revision_mark(const struct rev_info *revs, const struct commit *commit)
+const char *get_revision_mark(const struct rev_info *revs, const struct commit *commit)
 {
 	if (commit->object.flags & BOUNDARY)
 		return "-";
@@ -3966,7 +3966,7 @@ char *get_revision_mark(const struct rev_info *revs, const struct commit *commit
 
 void put_revision_mark(const struct rev_info *revs, const struct commit *commit)
 {
-	char *mark = get_revision_mark(revs, commit);
+	const char *mark = get_revision_mark(revs, commit);
 	if (!strlen(mark))
 		return;
 	fputs(mark, stdout);
diff --git a/revision.h b/revision.h
index 4134dc6029..addd69410b 100644
--- a/revision.h
+++ b/revision.h
@@ -322,8 +322,8 @@ int handle_revision_arg(const char *arg, struct rev_info *revs,
 void reset_revision_walk(void);
 int prepare_revision_walk(struct rev_info *revs);
 struct commit *get_revision(struct rev_info *revs);
-char *get_revision_mark(const struct rev_info *revs,
-			const struct commit *commit);
+const char *get_revision_mark(const struct rev_info *revs,
+			      const struct commit *commit);
 void put_revision_mark(const struct rev_info *revs,
 		       const struct commit *commit);
 
-- 
2.24.0.298.g3e88fbd976

[PATCH v2 04/10] revision: change abbrev_commit_given to abbrev_commit_explicit

[Denton Liu]

In a future patch, we want to know if `--[no-]abbrev-commit` arguments
have been explicitly provided. Since `rev_info.abbrev_commit_given` is
only used in one place, co-opt it to become
`rev_info.abbrev_commit_explicit`. This information will be used in a
future patch.

With this change, the semantics of the original usage (in
the `--pretty=raw` codepath) aren't altered.

Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
 builtin/log.c | 2 +-
 revision.c    | 3 ++-
 revision.h    | 2 +-
 3 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/builtin/log.c b/builtin/log.c
index 89873d2dc2..e4df16be79 100644
--- a/builtin/log.c
+++ b/builtin/log.c
@@ -230,7 +230,7 @@ static void cmd_log_init_finish(int argc, const char **argv, const char *prefix,
 		 */
 		if (!decoration_given)
 			decoration_style = 0;
-		if (!rev->abbrev_commit_given)
+		if (!rev->abbrev_commit_explicit)
 			rev->abbrev_commit = 0;
 	}
 
diff --git a/revision.c b/revision.c
index 2151b119b7..02b49ab754 100644
--- a/revision.c
+++ b/revision.c
@@ -2271,9 +2271,10 @@ static int handle_revision_opt(struct rev_info *revs, int argc, const char **arg
 			revs->abbrev = hexsz;
 	} else if (!strcmp(arg, "--abbrev-commit")) {
 		revs->abbrev_commit = 1;
-		revs->abbrev_commit_given = 1;
+		revs->abbrev_commit_explicit = 1;
 	} else if (!strcmp(arg, "--no-abbrev-commit")) {
 		revs->abbrev_commit = 0;
+		revs->abbrev_commit_explicit = 1;
 	} else if (!strcmp(arg, "--full-diff")) {
 		revs->diff = 1;
 		revs->full_diff = 1;
diff --git a/revision.h b/revision.h
index addd69410b..7670f29973 100644
--- a/revision.h
+++ b/revision.h
@@ -185,7 +185,7 @@ struct rev_info {
 			show_signature:1,
 			pretty_given:1,
 			abbrev_commit:1,
-			abbrev_commit_given:1,
+			abbrev_commit_explicit:1,
 			zero_commit:1,
 			use_terminator:1,
 			missing_newline:1,
-- 
2.24.0.298.g3e88fbd976

[PATCH v2 05/10] pretty.c: inline initalize format_context

[Denton Liu]

Instead of memsetting and then initializing the fields in the struct,
move the initialization of `format_context` to its assignment.

In preparation for a future commit where we mechanically move lines from
repo_format_commit_message() into a helper function,
`format_context.wrap_start` is not generically used so move its
assignment closer to its use.

Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
 pretty.c | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/pretty.c b/pretty.c
index b32f036953..6f2b0ad917 100644
--- a/pretty.c
+++ b/pretty.c
@@ -1610,14 +1610,13 @@ void repo_format_commit_message(struct repository *r,
 				const char *format, struct strbuf *sb,
 				const struct pretty_print_context *pretty_ctx)
 {
-	struct format_commit_context context;
+	struct format_commit_context context = {
+		.commit = commit,
+		.pretty_ctx = pretty_ctx
+	};
 	const char *output_enc = pretty_ctx->output_encoding;
 	const char *utf8 = "UTF-8";
 
-	memset(&context, 0, sizeof(context));
-	context.commit = commit;
-	context.pretty_ctx = pretty_ctx;
-	context.wrap_start = sb->len;
 	/*
 	 * convert a commit message to UTF-8 first
 	 * as far as 'format_commit_item' assumes it in UTF-8
@@ -1626,6 +1625,7 @@ void repo_format_commit_message(struct repository *r,
 					       &context.commit_encoding,
 					       utf8);
 
+	context.wrap_start = sb->len;
 	strbuf_expand(sb, format, format_commit_item, &context);
 	rewrap_message_tail(sb, &context, 0, 0, 0);
 
-- 
2.24.0.298.g3e88fbd976

[PATCH v2 06/10] pretty.c: extract functionality to repo_format_commit_generic()

[Denton Liu]

In a future commit, we will be reusing common functionality from
repo_format_commit_message(). Extract this common functionality into
repo_format_commit_generic() so that it can be reused in the future.

Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
 pretty.c | 35 ++++++++++++++++++++++++++++-------
 1 file changed, 28 insertions(+), 7 deletions(-)

diff --git a/pretty.c b/pretty.c
index 6f2b0ad917..a6e5fc115a 100644
--- a/pretty.c
+++ b/pretty.c
@@ -1605,10 +1605,14 @@ void userformat_find_requirements(const char *fmt, struct userformat_want *w)
 	strbuf_release(&dummy);
 }
 
-void repo_format_commit_message(struct repository *r,
-				const struct commit *commit,
-				const char *format, struct strbuf *sb,
-				const struct pretty_print_context *pretty_ctx)
+static void repo_format_commit_generic(struct repository *r,
+				       const struct commit *commit,
+				       struct strbuf *sb,
+				       const struct pretty_print_context *pretty_ctx,
+				       void (*fn)(struct strbuf *,
+						  struct format_commit_context *,
+						  void *),
+				       void *data)
 {
 	struct format_commit_context context = {
 		.commit = commit,
@@ -1625,9 +1629,7 @@ void repo_format_commit_message(struct repository *r,
 					       &context.commit_encoding,
 					       utf8);
 
-	context.wrap_start = sb->len;
-	strbuf_expand(sb, format, format_commit_item, &context);
-	rewrap_message_tail(sb, &context, 0, 0, 0);
+	fn(sb, &context, data);
 
 	/* then convert a commit message to an actual output encoding */
 	if (output_enc) {
@@ -1651,6 +1653,25 @@ void repo_format_commit_message(struct repository *r,
 	repo_unuse_commit_buffer(r, commit, context.message);
 }
 
+static void do_repo_format_commit_message(struct strbuf *sb,
+					  struct format_commit_context *context,
+					  void *data)
+{
+	const char *format = data;
+	context->wrap_start = sb->len;
+	strbuf_expand(sb, format, format_commit_item, context);
+	rewrap_message_tail(sb, context, 0, 0, 0);
+}
+
+void repo_format_commit_message(struct repository *r,
+				const struct commit *commit,
+				const char *format, struct strbuf *sb,
+				const struct pretty_print_context *pretty_ctx)
+{
+	repo_format_commit_generic(r, commit, sb, pretty_ctx,
+				   do_repo_format_commit_message, (void *)format);
+}
+
 static void pp_header(struct pretty_print_context *pp,
 		      const char *encoding,
 		      const struct commit *commit,
-- 
2.24.0.298.g3e88fbd976

[PATCH v2 07/10] t4205: cover `git log --reflog -z` blindspot

[Denton Liu]

The test suite does not include any tests where `--reflog` and `-z` are
used together in `git log`. Cover this blindspot. Note that the
`--pretty=oneline` case is written separately because it follows a
slightly different codepath.

Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
 t/t4205-log-pretty-formats.sh | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/t/t4205-log-pretty-formats.sh b/t/t4205-log-pretty-formats.sh
index f42a69faa2..d35650cae7 100755
--- a/t/t4205-log-pretty-formats.sh
+++ b/t/t4205-log-pretty-formats.sh
@@ -134,6 +134,41 @@ test_expect_failure C_LOCALE_OUTPUT 'NUL termination with --stat' '
 	test_cmp expected actual
 '
 
+emit_nul () {
+	echo | tr '\n' '\000'
+}
+
+for p in short medium full fuller email raw
+do
+	test_expect_success "NUL termination with --reflog --pretty=$p" '
+		>expect &&
+		revs="$(git rev-list --reflog)" &&
+		for r in $revs
+		do
+			git show -s "$r" --pretty='$p' >>expect || return 1
+			emit_nul >>expect
+		done &&
+		git log -z --reflog --pretty='$p' >actual &&
+		emit_nul >>actual &&
+		test_cmp expect actual
+	'
+done
+
+test_expect_success 'NUL termination with --reflog --pretty=oneline' '
+	>expect &&
+	revs="$(git rev-list --reflog)" &&
+	for r in $revs
+	do
+		# trim trailing newline
+		output="$(git show -s --pretty=oneline "$r")" || return 1
+		printf "%s" "$output" >>expect
+		emit_nul >>expect
+	done &&
+	git log -z --pretty=oneline --reflog >actual &&
+	# no trailing NUL
+	test_cmp expect actual
+'
+
 test_expect_success 'setup more commits' '
 	test_commit "message one" one one message-one &&
 	test_commit "message two" two two message-two &&
-- 
2.24.0.298.g3e88fbd976

[PATCH v2 08/10] reflog-walk.c: move where the newline is added

[Denton Liu]

In a future commit, we want to possibly be able to continue the reflog message on
the same line without breaking the line. As a result, when
`oneline == 1`, strip any trailing new lines.

Add these missing newlines back in show_log().

While we're at it, cuddle the else with the closing brace of the if to
more closely match the existing style.

Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
 log-tree.c    | 4 +++-
 reflog-walk.c | 8 +++++---
 2 files changed, 8 insertions(+), 4 deletions(-)

diff --git a/log-tree.c b/log-tree.c
index 923a299e70..4a7d668af6 100644
--- a/log-tree.c
+++ b/log-tree.c
@@ -661,8 +661,10 @@ void show_log(struct rev_info *opt)
 					    opt->commit_format == CMIT_FMT_ONELINE,
 					    &opt->date_mode,
 					    opt->date_mode_explicit);
-			if (opt->commit_format == CMIT_FMT_ONELINE)
+			if (opt->commit_format == CMIT_FMT_ONELINE) {
+				putc('\n', opt->diffopt.file);
 				return;
+			}
 		}
 	}
 
diff --git a/reflog-walk.c b/reflog-walk.c
index 3a25b27d8f..6b6bd18e6c 100644
--- a/reflog-walk.c
+++ b/reflog-walk.c
@@ -285,9 +285,11 @@ void show_reflog_message(struct reflog_walk_info *reflog_info, int oneline,
 		info = &commit_reflog->reflogs->items[commit_reflog->recno+1];
 		get_reflog_selector(&selector, reflog_info, dmode, force_date, 0);
 		if (oneline) {
-			printf("%s: %s", selector.buf, info->message);
-		}
-		else {
+			int len = strlen(info->message);
+			if (len > 0)
+				len--; /* strip away trailing newline */
+			printf("%s: %.*s", selector.buf, len, info->message);
+		} else {
 			printf("Reflog: %s (%s)\nReflog message: %s",
 			       selector.buf, info->email, info->message);
 		}
-- 
2.24.0.298.g3e88fbd976

[PATCH v2 09/10] pretty: implement 'summary' format

[Denton Liu]

The standard format for referencing other commits within some projects
(such as git.git) is the summary format. This is described in
Documentation/SubmittingPatches as

	If you want to reference a previous commit in the history of a stable
	branch, use the format "abbreviated hash (subject, date)",
	with the subject enclosed in a pair of double-quotes, like this:

	....
		Commit f86a374 ("pack-bitmap.c: fix a memleak", 2015-03-30)
		noticed that ...
	....

Since this format is so commonly used, standardize it as a pretty
format.

This format is implemented as a separate flow that skips most of
pretty_print_commit() and instead calls format_commit_summary(). The
reason why this is done is because the other pretty formats expect
output to be generated in a specific order. Specifically, the header,
including the date, is always printed before the commit message,
including the subject. Reversing the order would be possible but would
involve butchering pretty_print_commit() so it is implemented as a
separate flow.

Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
 Documentation/pretty-formats.txt   |  9 ++++
 Documentation/pretty-options.txt   |  2 +-
 Documentation/rev-list-options.txt |  2 +-
 builtin/log.c                      | 30 +++++++++--
 log-tree.c                         | 11 ++--
 pretty.c                           | 31 ++++++++++-
 pretty.h                           |  1 +
 t/t4205-log-pretty-formats.sh      | 83 +++++++++++++++++++++++++-----
 8 files changed, 144 insertions(+), 25 deletions(-)

diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt
index 71eef684d0..f9c1296d7c 100644
--- a/Documentation/pretty-formats.txt
+++ b/Documentation/pretty-formats.txt
@@ -63,6 +63,15 @@ This is designed to be as compact as possible.
 
 	       <full commit message>
 
+* 'summary'
+
+	  <abbrev hash> ("<title line>", <short author date>)
++
+This format is useful for referring to other commits when writing a new
+commit message. Although by default, '<abbrev hash>' is used, this can
+be overridden with '--no-abbrev'. In addition, '<short author date>' can
+be overridden by with '--date='.
+
 * 'email'
 
 	  From <hash> <date>
diff --git a/Documentation/pretty-options.txt b/Documentation/pretty-options.txt
index e44fc8f738..0a5b206193 100644
--- a/Documentation/pretty-options.txt
+++ b/Documentation/pretty-options.txt
@@ -3,7 +3,7 @@
 
 	Pretty-print the contents of the commit logs in a given format,
 	where '<format>' can be one of 'oneline', 'short', 'medium',
-	'full', 'fuller', 'email', 'raw', 'format:<string>'
+	'full', 'fuller', 'summary', 'email', 'raw', 'format:<string>'
 	and 'tformat:<string>'.  When '<format>' is none of the above,
 	and has '%placeholder' in it, it acts as if
 	'--pretty=tformat:<format>' were given.
diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
index 90ff9e2bea..76df494ed6 100644
--- a/Documentation/rev-list-options.txt
+++ b/Documentation/rev-list-options.txt
@@ -289,7 +289,7 @@ depending on a few rules:
 4. Otherwise, show the index format.
 --
 +
-Under `--pretty=oneline`, the commit message is
+Under `--pretty=oneline` and `--pretty=summary`, 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].
diff --git a/builtin/log.c b/builtin/log.c
index e4df16be79..ad96a746a3 100644
--- a/builtin/log.c
+++ b/builtin/log.c
@@ -223,15 +223,35 @@ static void cmd_log_init_finish(int argc, const char **argv, const char *prefix,
 		read_mailmap(rev->mailmap, NULL);
 	}
 
-	if (rev->pretty_given && rev->commit_format == CMIT_FMT_RAW) {
+	if (rev->pretty_given) {
+		switch (rev->commit_format) {
+
 		/*
 		 * "log --pretty=raw" is special; ignore UI oriented
 		 * configuration variables such as decoration.
 		 */
-		if (!decoration_given)
-			decoration_style = 0;
-		if (!rev->abbrev_commit_explicit)
-			rev->abbrev_commit = 0;
+		case CMIT_FMT_RAW:
+			if (!decoration_given)
+				decoration_style = 0;
+			if (!rev->abbrev_commit_explicit)
+				rev->abbrev_commit = 0;
+			break;
+
+		/*
+		 * "log --pretty=summary" is special; ignore UI oriented
+		 * configuration variables such as decoration but keep
+		 * abbreviations.
+		 */
+		case CMIT_FMT_SUMMARY:
+			if (!decoration_given)
+				decoration_style = 0;
+			if (!rev->abbrev_commit_explicit)
+				rev->abbrev_commit = 1;
+			break;
+
+		default:
+			break;
+		}
 	}
 
 	if (decoration_style) {
diff --git a/log-tree.c b/log-tree.c
index 4a7d668af6..433adaf0f1 100644
--- a/log-tree.c
+++ b/log-tree.c
@@ -627,7 +627,8 @@ void show_log(struct rev_info *opt)
 		ctx.print_email_subject = 1;
 	} else if (opt->commit_format != CMIT_FMT_USERFORMAT) {
 		fputs(diff_get_color_opt(&opt->diffopt, DIFF_COMMIT), opt->diffopt.file);
-		if (opt->commit_format != CMIT_FMT_ONELINE)
+		if (opt->commit_format != CMIT_FMT_ONELINE &&
+		    opt->commit_format != CMIT_FMT_SUMMARY)
 			fputs("commit ", opt->diffopt.file);
 
 		if (!opt->graph)
@@ -644,7 +645,8 @@ void show_log(struct rev_info *opt)
 			       find_unique_abbrev(&parent->object.oid, abbrev_commit));
 		fputs(diff_get_color_opt(&opt->diffopt, DIFF_RESET), opt->diffopt.file);
 		show_decorations(opt, commit);
-		if (opt->commit_format == CMIT_FMT_ONELINE) {
+		if (opt->commit_format == CMIT_FMT_ONELINE ||
+		    opt->commit_format == CMIT_FMT_SUMMARY) {
 			putc(' ', opt->diffopt.file);
 		} else {
 			putc('\n', opt->diffopt.file);
@@ -658,12 +660,15 @@ void show_log(struct rev_info *opt)
 			 * graph info here.
 			 */
 			show_reflog_message(opt->reflog_info,
-					    opt->commit_format == CMIT_FMT_ONELINE,
+					    (opt->commit_format == CMIT_FMT_ONELINE ||
+					     opt->commit_format == CMIT_FMT_SUMMARY),
 					    &opt->date_mode,
 					    opt->date_mode_explicit);
 			if (opt->commit_format == CMIT_FMT_ONELINE) {
 				putc('\n', opt->diffopt.file);
 				return;
+			} else if (opt->commit_format == CMIT_FMT_SUMMARY) {
+				putc(' ', opt->diffopt.file);
 			}
 		}
 	}
diff --git a/pretty.c b/pretty.c
index a6e5fc115a..8efb2486a5 100644
--- a/pretty.c
+++ b/pretty.c
@@ -97,7 +97,8 @@ static void setup_commit_formats(void)
 		{ "mboxrd",	CMIT_FMT_MBOXRD,	0,	0 },
 		{ "fuller",	CMIT_FMT_FULLER,	0,	8 },
 		{ "full",	CMIT_FMT_FULL,		0,	8 },
-		{ "oneline",	CMIT_FMT_ONELINE,	1,	0 }
+		{ "oneline",	CMIT_FMT_ONELINE,	1,	0 },
+		{ "summary",	CMIT_FMT_SUMMARY,	1,	0 },
 		/*
 		 * Please update $__git_log_pretty_formats in
 		 * git-completion.bash when you add new formats.
@@ -1672,6 +1673,26 @@ void repo_format_commit_message(struct repository *r,
 				   do_repo_format_commit_message, (void *)format);
 }
 
+static void do_repo_format_commit_summary(struct strbuf *sb,
+					  struct format_commit_context *context,
+					  void *additional_context)
+{
+	struct ident_split ident;
+
+	parse_commit_header(context);
+	parse_commit_message(context);
+
+	strbuf_addstr(sb, "(\"");
+	format_subject(sb, context->message + context->subject_off, " ");
+	if (!split_ident_line(&ident,
+			      context->message + context->author.off,
+			      context->author.len)) {
+		strbuf_addstr(sb, "\", ");
+		strbuf_addstr(sb, show_ident_date(&ident, &context->pretty_ctx->date_mode));
+	}
+	strbuf_addstr(sb, ")");
+}
+
 static void pp_header(struct pretty_print_context *pp,
 		      const char *encoding,
 		      const struct commit *commit,
@@ -1923,6 +1944,14 @@ void pretty_print_commit(struct pretty_print_context *pp,
 		format_commit_message(commit, user_format, sb, pp);
 		return;
 	}
+	if (pp->fmt == CMIT_FMT_SUMMARY) {
+		if (!pp->date_mode_explicit)
+			pp->date_mode = *DATE_MODE(SHORT);
+
+		repo_format_commit_generic(the_repository, commit, sb, pp,
+					   do_repo_format_commit_summary, NULL);
+		return;
+	}
 
 	encoding = get_log_output_encoding();
 	msg = reencoded = logmsg_reencode(commit, NULL, encoding);
diff --git a/pretty.h b/pretty.h
index 4ad1fc31ff..6d5b18a4f1 100644
--- a/pretty.h
+++ b/pretty.h
@@ -16,6 +16,7 @@ enum cmit_fmt {
 	CMIT_FMT_FULL,
 	CMIT_FMT_FULLER,
 	CMIT_FMT_ONELINE,
+	CMIT_FMT_SUMMARY,
 	CMIT_FMT_EMAIL,
 	CMIT_FMT_MBOXRD,
 	CMIT_FMT_USERFORMAT,
diff --git a/t/t4205-log-pretty-formats.sh b/t/t4205-log-pretty-formats.sh
index d35650cae7..fcfd66faf9 100755
--- a/t/t4205-log-pretty-formats.sh
+++ b/t/t4205-log-pretty-formats.sh
@@ -154,20 +154,23 @@ do
 	'
 done
 
-test_expect_success 'NUL termination with --reflog --pretty=oneline' '
-	>expect &&
-	revs="$(git rev-list --reflog)" &&
-	for r in $revs
-	do
-		# trim trailing newline
-		output="$(git show -s --pretty=oneline "$r")" || return 1
-		printf "%s" "$output" >>expect
-		emit_nul >>expect
-	done &&
-	git log -z --pretty=oneline --reflog >actual &&
-	# no trailing NUL
-	test_cmp expect actual
-'
+for p in oneline summary
+do
+	test_expect_success "NUL termination with --reflog --pretty=$p" '
+		>expect &&
+		revs="$(git rev-list --reflog)" &&
+		for r in $revs
+		do
+			# trim trailing newline
+			output="$(git show -s --pretty='$p' "$r")" || return 1
+			printf "%s" "$output" >>expect
+			emit_nul >>expect
+		done &&
+		git log -z --pretty='$p' --reflog >actual &&
+		# no trailing NUL
+		test_cmp expect actual
+	'
+done
 
 test_expect_success 'setup more commits' '
 	test_commit "message one" one one message-one &&
@@ -823,4 +826,56 @@ test_expect_success '%S in git log --format works with other placeholders (part
 	test_cmp expect actual
 '
 
+test_expect_success 'log --pretty=summary' '
+	git log --date=short --pretty="tformat:%h (\"%s\", %ad)" >expect &&
+	git log --pretty=summary >actual &&
+	test_cmp expect actual
+'
+
+test_expect_success 'log --pretty=summary with log.date is overridden by short date' '
+	git log --date=short --pretty="tformat:%h (\"%s\", %ad)" >expect &&
+	test_config log.date rfc &&
+	git log --pretty=summary >actual &&
+	test_cmp expect actual
+'
+
+test_expect_success 'log --pretty=summary with explicit date overrides short date' '
+	git log --date=rfc --pretty="tformat:%h (\"%s\", %ad)" >expect &&
+	git log --date=rfc --pretty=summary >actual &&
+	test_cmp expect actual
+'
+
+test_expect_success 'log --pretty=summary with log.abbrevCommit is overidden' '
+	git log --date=short --pretty="tformat:%h (\"%s\", %ad)" >expect &&
+	test_config log.abbrevCommit false &&
+	git log --pretty=summary >actual &&
+	test_cmp expect actual
+'
+
+test_expect_success 'log --pretty=summary with explicit --no-abbrev overrides abbreviated' '
+	git log --date=short --pretty="tformat:%H (\"%s\", %ad)" >expect &&
+	git log --no-abbrev --pretty=summary >actual &&
+	test_cmp expect actual
+'
+
+test_expect_success 'log --pretty=summary with log.decorate is overridden' '
+	git log --date=short --pretty="tformat:%h (\"%s\", %ad)" >expect &&
+	test_config log.decorate short &&
+	git log --pretty=summary >actual &&
+	test_cmp expect actual
+'
+
+test_expect_success 'log --pretty=summary with explicit decorate overrides no decoration' '
+	git log --date=short --pretty="tformat:%h%d (\"%s\", %ad)" >expect &&
+	git log --decorate=short --pretty=summary >actual &&
+	test_cmp expect actual
+'
+
+test_expect_success 'log --pretty=summary with --walk-reflogs' '
+	test_config log.date short &&
+	git log --walk-reflogs --pretty="tformat:%h %gd: %gs (\"%s\", %ad)" >expect &&
+	git log --walk-reflogs --pretty=summary >actual &&
+	test_cmp expect actual
+'
+
 test_done
-- 
2.24.0.298.g3e88fbd976

[PATCH v2 10/10] SubmittingPatches: use `--pretty=summary`

[Denton Liu]

Since Git was taught the `--pretty=summary` option, it is no longer
necessary to manually specify the format string to get the commit
summary. Teach users to use the new option while keeping the old
invocation around in case they have an older version of Git.

Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
 Documentation/SubmittingPatches | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index bb7e33ce15..849d27663e 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -153,6 +153,12 @@ with the subject enclosed in a pair of double-quotes, like this:
 The "Copy commit summary" command of gitk can be used to obtain this
 format, or this invocation of `git show`:
 
+....
+	git show -s --pretty=summary <commit>
+....
+
+or, on an older version of Git without support for --pretty=summary:
+
 ....
 	git show -s --date=short --pretty='format:%h ("%s", %ad)' <commit>
 ....
-- 
2.24.0.298.g3e88fbd976

Re: [PATCH v2 07/10] t4205: cover `git log --reflog -z` blindspot

[Eric Sunshine]

On Fri, Nov 8, 2019 at 3:08 PM Denton Liu <liu.denton@gmail.com> wrote:
> The test suite does not include any tests where `--reflog` and `-z` are
> used together in `git log`. Cover this blindspot. Note that the
> `--pretty=oneline` case is written separately because it follows a
> slightly different codepath.
>
> Signed-off-by: Denton Liu <liu.denton@gmail.com>
> ---
> diff --git a/t/t4205-log-pretty-formats.sh b/t/t4205-log-pretty-formats.sh
> @@ -134,6 +134,41 @@ test_expect_failure C_LOCALE_OUTPUT 'NUL termination with --stat' '
> +emit_nul () {
> +       echo | tr '\n' '\000'
> +}

A simple:

    printf "\0"

would be simpler, and I don't think you even need to introduce a shell
function to encapsulate it, as it's quite clear at a glance what it
does.

> +for p in short medium full fuller email raw
> +do
> +       test_expect_success "NUL termination with --reflog --pretty=$p" '
> +               >expect &&

You can drop this line...

> +               revs="$(git rev-list --reflog)" &&
> +               for r in $revs
> +               do
> +                       git show -s "$r" --pretty='$p' >>expect || return 1
> +                       emit_nul >>expect

...and simplify all this capturing into 'expect'...

> +               done &&

... by just redirecting the output of the for-loop itself:

    for r in $(git rev-list --reflog)
    do
        git show -s --pretty="$p" "$r" &&
        printf "\0" || return 1
    done >expect &&

For completeness, the above example also drops the unnecessary 'revs'
variable, uses double quotes rather than single when interpolating $p,
and makes the loop early-exit a bit more idiomatic.

> +               git log -z --reflog --pretty='$p' >actual &&
> +               emit_nul >>actual &&

Likewise, you can capture 'actual' in its entirety:

    {
        git log -z --reflog --pretty="$p" &&
        printf "\0"
    } >actual &&

> +               test_cmp expect actual
> +       '
> +done
> +
> +test_expect_success 'NUL termination with --reflog --pretty=oneline' '
> +       >expect &&
> +       revs="$(git rev-list --reflog)" &&
> +       for r in $revs
> +       do
> +               # trim trailing newline
> +               output="$(git show -s --pretty=oneline "$r")" || return 1
> +               printf "%s" "$output" >>expect
> +               emit_nul >>expect
> +       done &&

Replacing the newline with NUL could be done more simply and
idiomatically (with regard to other test scripts) by passing the
output of "git show" through the lf_to_nul() function from
test-lib-functions.sh. Something like this should do it:

    for r in $(git rev-list --reflog)
    do
        git show -s --pretty=oneline "$r" >raw &&
        cat raw | lf_to_nul || return 1
    done >expect &&

> +       git log -z --pretty=oneline --reflog >actual &&
> +       # no trailing NUL

To what is this comment referring?

> +       test_cmp expect actual
> +'

Re: [PATCH v2 09/10] pretty: implement 'summary' format

[Eric Sunshine]

On Fri, Nov 8, 2019 at 3:08 PM Denton Liu <liu.denton@gmail.com> wrote:
> Signed-off-by: Denton Liu <liu.denton@gmail.com>
> ---
> diff --git a/t/t4205-log-pretty-formats.sh b/t/t4205-log-pretty-formats.sh
> @@ -154,20 +154,23 @@ do
> -test_expect_success 'NUL termination with --reflog --pretty=oneline' '
> -       >expect &&
> -       revs="$(git rev-list --reflog)" &&
> -       [...]
> -       test_cmp expect actual
> -'
> +for p in oneline summary
> +do
> +       test_expect_success "NUL termination with --reflog --pretty=$p" '
> +               >expect &&
> +               revs="$(git rev-list --reflog)" &&
> +               [...]
> +               test_cmp expect actual
> +       '
> +done

This patch would be less noisy (by eliminating the indentation change)
if you wrapped this test in a for-loop back in 7/10 where it was
introduced, with the intention of adding more items to the 'for' list.
So, in 7/10, you'd have this:

    for p in online
    do
        test_expect_success "NUL termination with --reflog --pretty=$p" '
            ...
        '
    done

and this patch, 9/10, would just make the minor change:

    -for p in oneline
    +for p in oneline summary

Having a for-loop with only a single item is a minor-ugly which pays
off with less noise in subsequent patch(es), thus easing review
burden.

Re: [PATCH v2 07/10] t4205: cover `git log --reflog -z` blindspot

[Denton Liu]

Hi Eric,

On Fri, Nov 08, 2019 at 03:36:25PM -0500, Eric Sunshine wrote:

[...]

>     for r in $(git rev-list --reflog)
>     do
>         git show -s --pretty="$p" "$r" &&
>         printf "\0" || return 1
>     done >expect &&
> 
> For completeness, the above example also drops the unnecessary 'revs'
> variable, uses double quotes rather than single when interpolating $p,
> and makes the loop early-exit a bit more idiomatic.

The reason why I pulled out `revs` was because putting the rev-list
within the for-loop would cause its exit code to be lost if it ever
failed. Since I've been cleaning up test scripts to not lose exit codes
from git commands, I figured it'd be a bad idea to introduce an instance
here ;)

Thanks for the other two suggestions, though. I didn't know that you
could write it like that.

> > +       git log -z --pretty=oneline --reflog >actual &&
> > +       # no trailing NUL
> 
> To what is this comment referring?

I wanted to point out how in the oneline case, the trailing NUL is
already included, unlike in the multiple cases, so we don't need to
output another one.

I'll rewrite this as

	# the trailing NUL is already produced so we don't need to
	# output another one

Thanks for your feedback,

Denton

Re: [PATCH v2 07/10] t4205: cover `git log --reflog -z` blindspot

[Eric Sunshine]

On Fri, Nov 8, 2019 at 4:47 PM Denton Liu <liu.denton@gmail.com> wrote:
> On Fri, Nov 08, 2019 at 03:36:25PM -0500, Eric Sunshine wrote:
> > For completeness, the above example also drops the unnecessary 'revs'
> > variable, uses double quotes rather than single when interpolating $p,
> > and makes the loop early-exit a bit more idiomatic.
>
> The reason why I pulled out `revs` was because putting the rev-list
> within the for-loop would cause its exit code to be lost if it ever
> failed. Since I've been cleaning up test scripts to not lose exit codes
> from git commands, I figured it'd be a bad idea to introduce an instance
> here ;)

Make sense. Ignore that suggestion of mine.

> > > +       git log -z --pretty=oneline --reflog >actual &&
> > > +       # no trailing NUL
> >
> > To what is this comment referring?
>
> I wanted to point out how in the oneline case, the trailing NUL is
> already included, unlike in the multiple cases, so we don't need to
> output another one.
>
> I'll rewrite this as
>
>         # the trailing NUL is already produced so we don't need to
>         # output another one

That will be clearer. It might be even clearer if that comment comes
before the "git log -z" invocation rather than after (though that's
subjective). Thanks.

Re: [PATCH v2 09/10] pretty: implement 'summary' format

[René Scharfe]

Am 08.11.19 um 21:08 schrieb Denton Liu:
> The standard format for referencing other commits within some projects
> (such as git.git) is the summary format. This is described in
> Documentation/SubmittingPatches as
>
> 	If you want to reference a previous commit in the history of a stable
> 	branch, use the format "abbreviated hash (subject, date)",
> 	with the subject enclosed in a pair of double-quotes, like this:
>
> 	....
> 		Commit f86a374 ("pack-bitmap.c: fix a memleak", 2015-03-30)
> 		noticed that ...
> 	....
>
> Since this format is so commonly used, standardize it as a pretty
> format.
>
> This format is implemented as a separate flow that skips most of
> pretty_print_commit() and instead calls format_commit_summary(). The
> reason why this is done is because the other pretty formats expect
> output to be generated in a specific order. Specifically, the header,
> including the date, is always printed before the commit message,
> including the subject. Reversing the order would be possible but would
> involve butchering pretty_print_commit() so it is implemented as a
> separate flow.
>
> Signed-off-by: Denton Liu <liu.denton@gmail.com>
> ---
>  Documentation/pretty-formats.txt   |  9 ++++
>  Documentation/pretty-options.txt   |  2 +-
>  Documentation/rev-list-options.txt |  2 +-
>  builtin/log.c                      | 30 +++++++++--
>  log-tree.c                         | 11 ++--
>  pretty.c                           | 31 ++++++++++-
>  pretty.h                           |  1 +
>  t/t4205-log-pretty-formats.sh      | 83 +++++++++++++++++++++++++-----
>  8 files changed, 144 insertions(+), 25 deletions(-)

Hmm, that's quite a lot of code to add to the formatting code with its
repeated special-case checks.  Why not implement it as a built-in user
format, like making it an alias for something like this?

   git log --format='%C(auto)%h ("%s", %as)'

We don't have %as, yet, but making --date=short available as a
placeholder would be a good idea anyway (patch below).


-- >8 --
Subject: [PATCH] pretty: provide short date format

Add the placeholders %as and %cs to format author date and committer
date, respectively, without the time part, like --date=short does, i.e.
like YYYY-MM-DD.

Signed-off-by: René Scharfe <l.s.r@web.de>
---
 Documentation/pretty-formats.txt | 2 ++
 pretty.c                         | 3 +++
 t/t4205-log-pretty-formats.sh    | 6 ++++++
 3 files changed, 11 insertions(+)

diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt
index b87e2e83e6..f80eaab439 100644
--- a/Documentation/pretty-formats.txt
+++ b/Documentation/pretty-formats.txt
@@ -169,6 +169,7 @@ The placeholders are:
 '%at':: author date, UNIX timestamp
 '%ai':: author date, ISO 8601-like format
 '%aI':: author date, strict ISO 8601 format
+'%as':: author date, short format (`YYYY-MM-DD`)
 '%cn':: committer name
 '%cN':: committer name (respecting .mailmap, see
 	linkgit:git-shortlog[1] or linkgit:git-blame[1])
@@ -181,6 +182,7 @@ The placeholders are:
 '%ct':: committer date, UNIX timestamp
 '%ci':: committer date, ISO 8601-like format
 '%cI':: committer date, strict ISO 8601 format
+'%cs':: committer date, short format (`YYYY-MM-DD`)
 '%d':: ref names, like the --decorate option of linkgit:git-log[1]
 '%D':: ref names without the " (", ")" wrapping.
 '%S':: ref name given on the command line by which the commit was reached
diff --git a/pretty.c b/pretty.c
index b32f036953..76920c91dd 100644
--- a/pretty.c
+++ b/pretty.c
@@ -731,6 +731,9 @@ static size_t format_person_part(struct strbuf *sb, char part,
 	case 'I':	/* date, ISO 8601 strict */
 		strbuf_addstr(sb, show_ident_date(&s, DATE_MODE(ISO8601_STRICT)));
 		return placeholder_len;
+	case 's':
+		strbuf_addstr(sb, show_ident_date(&s, DATE_MODE(SHORT)));
+		return placeholder_len;
 	}

 skip:
diff --git a/t/t4205-log-pretty-formats.sh b/t/t4205-log-pretty-formats.sh
index f42a69faa2..4980ed4c6f 100755
--- a/t/t4205-log-pretty-formats.sh
+++ b/t/t4205-log-pretty-formats.sh
@@ -503,6 +503,12 @@ test_expect_success 'ISO and ISO-strict date formats display the same values' '
 	test_cmp expected actual
 '

+test_expect_success 'short date' '
+	git log --format=%ad%n%cd --date=short >expected &&
+	git log --format=%as%n%cs >actual &&
+	test_cmp expected actual
+'
+
 # get new digests (with no abbreviations)
 test_expect_success 'set up log decoration tests' '
 	head1=$(git rev-parse --verify HEAD~0) &&
--
2.24.0

Re: [PATCH v2 09/10] pretty: implement 'summary' format

[René Scharfe]

Am 08.11.19 um 21:08 schrieb Denton Liu:
> The standard format for referencing other commits within some projects
> (such as git.git) is the summary format. This is described in
> Documentation/SubmittingPatches as
>
> 	If you want to reference a previous commit in the history of a stable
> 	branch, use the format "abbreviated hash (subject, date)",
> 	with the subject enclosed in a pair of double-quotes, like this:
>
> 	....
> 		Commit f86a374 ("pack-bitmap.c: fix a memleak", 2015-03-30)
> 		noticed that ...
> 	....
>
> Since this format is so commonly used, standardize it as a pretty
> format.

If the title contains a double quote then we get results like these:

   26b455f21e ("hashmap_put takes "struct hashmap_entry *"", 2019-10-06)
   01991cee86 ("config/alias.txt: change " and ' to `", 2019-06-05)

I noticed the lack of quoting in the code and was worried about the
output being confusing or unclean, but after staring at the examples
above for a while I find that it's not that bad.  It's reversible by
removing the outer quotes.  So perhaps we can keep it like this.

René

Re: [PATCH v2 09/10] pretty: implement 'summary' format

[Junio C Hamano]

René Scharfe <l.s.r@web.de> writes:

> Hmm, that's quite a lot of code to add to the formatting code with its
> repeated special-case checks.  Why not implement it as a built-in user
> format, like making it an alias for something like this?
>
>    git log --format='%C(auto)%h ("%s", %as)'
>
> We don't have %as, yet, but making --date=short available as a
> placeholder would be a good idea anyway (patch below).

Yes!  Implementing the 'summary' internally as merely an alias to a
canned user format does sound like the right approach.

Further, instead of inventing %as, I think you could just use %ad
there, and when 'summary' uses that canned user format, flip the
default date format to short.

That way, "git show -s --pretty=summary --date=iso" would be
available to those who like the format.

Thanks.

Re: [PATCH v2 09/10] pretty: implement 'summary' format

[Denton Liu]

Hi all,

On Sun, Nov 10, 2019 at 03:25:41PM +0900, Junio C Hamano wrote:
> René Scharfe <l.s.r@web.de> writes:
> 
> > Hmm, that's quite a lot of code to add to the formatting code with its
> > repeated special-case checks.  Why not implement it as a built-in user
> > format, like making it an alias for something like this?
> >
> >    git log --format='%C(auto)%h ("%s", %as)'
> >
> > We don't have %as, yet, but making --date=short available as a
> > placeholder would be a good idea anyway (patch below).
> 
> Yes!  Implementing the 'summary' internally as merely an alias to a
> canned user format does sound like the right approach.

We don't have any canned user formats currently, do we? I'm trying to
figure out where to insert the code to do this.

Is the idea to just insert a row in the builtin_formats[] table in
setup_commit_formats() with the `user_format` field populated?

> 
> Further, instead of inventing %as, I think you could just use %ad
> there, and when 'summary' uses that canned user format, flip the
> default date format to short.
> 
> That way, "git show -s --pretty=summary --date=iso" would be
> available to those who like the format.

If we do implement it as a canned format, then we lose support for
displaying `--no-abbrev`, `--walk-reflogs`, `--decorate`. Would we be
okay with this?

Thanks,

Denton

> 
> Thanks.

Re: [PATCH v2 09/10] pretty: implement 'summary' format

[SZEDER Gábor]

On Mon, Nov 11, 2019 at 03:47:10PM -0800, Denton Liu wrote:
> On Sun, Nov 10, 2019 at 03:25:41PM +0900, Junio C Hamano wrote:
> > René Scharfe <l.s.r@web.de> writes:
> > 
> > > Hmm, that's quite a lot of code to add to the formatting code with its
> > > repeated special-case checks.  Why not implement it as a built-in user
> > > format, like making it an alias for something like this?
> > >
> > >    git log --format='%C(auto)%h ("%s", %as)'
> > >
> > > We don't have %as, yet, but making --date=short available as a
> > > placeholder would be a good idea anyway (patch below).
> > 
> > Yes!  Implementing the 'summary' internally as merely an alias to a
> > canned user format does sound like the right approach.
> 
> We don't have any canned user formats currently, do we? I'm trying to
> figure out where to insert the code to do this.
> 
> Is the idea to just insert a row in the builtin_formats[] table in
> setup_commit_formats() with the `user_format` field populated?

Yeah, it's as simple as adding:

  { "reference",  CMIT_FMT_USERFORMAT,    1,      0, 0, "%C(auto)%h (%s, %as)" }

Works like a charm, I've been using it for a few years now:

  https://github.com/szeder/git/commit/3604d0c28e7e2da5415986468994ef71a972e4ed

but never seriously considered for submission, because I didn't want
to argue about removing the double-quotes around the subject, and
couldn't be bothered to check the corner cases (e.g. what if a user
sets a pretty format alias with the same name in the configuration?).

Re: [PATCH v2 09/10] pretty: implement 'summary' format

[SZEDER Gábor]

On Fri, Nov 08, 2019 at 12:08:34PM -0800, Denton Liu wrote:
> The standard format for referencing other commits within some projects
> (such as git.git) is the summary format. This is described in
> Documentation/SubmittingPatches as
> 
> 	If you want to reference a previous commit in the history of a stable
> 	branch, use the format "abbreviated hash (subject, date)",
> 	with the subject enclosed in a pair of double-quotes, like this:
> 
> 	....
> 		Commit f86a374 ("pack-bitmap.c: fix a memleak", 2015-03-30)
> 		noticed that ...
> 	....
> 
> Since this format is so commonly used, standardize it as a pretty
> format.

SubmittingPatches is simply wrong: our de-facto standard format for
referencing other commits does not enclose the subject in a pair of
double-quotes:

  $ git log v2.24.0 |grep -E '[0-9a-f]{7} \("' |wc -l
  785
  $ git log v2.24.0 |grep -E '[0-9a-f]{7} \([^"]' |wc -l
  2276

Those double-quotes don't add any value to the references, but they
result in weird looking references for 1083 of our commits whose
subject lines happen to end with double-quotes, e.g.:

  f23a465132 ("hashmap_get{,_from_hash} return "struct hashmap_entry *"", 2019-10-06)

and without those unnecessary pair of double-quotes we would have
~3000 more commits whose summary would fit on a single line.

Re: [PATCH v2 09/10] pretty: implement 'summary' format

[Junio C Hamano]

SZEDER Gábor <szeder.dev@gmail.com> writes:

> Yeah, it's as simple as adding:
>
>   { "reference",  CMIT_FMT_USERFORMAT,    1,      0, 0, "%C(auto)%h (%s, %as)" }
>
> Works like a charm, I've been using it for a few years now:
>
>   https://github.com/szeder/git/commit/3604d0c28e7e2da5415986468994ef71a972e4ed

The word "reference" does sound more to the point for the feature
than "summary", and it is nice to see that the required change is
essentially a single liner ;-)

> but never seriously considered for submission, because I didn't want
> to argue about removing the double-quotes around the subject, and

I personally do not care whether the title is naked or inside a
dq-pair, as that part is purely for human consumption.  Being for
human consumption, I guess we can argue that the shorter the better,
so we may want to standardise the recommendation we give in our
tutorials and such.

> couldn't be bothered to check the corner cases (e.g. what if a user
> sets a pretty format alias with the same name in the configuration?).

It would be already possible to collide with built-in names, like
"short", with or without your addition, wouldn't it?  Then that is
not an issue you would need to be worried about, right?

Thanks.

[PATCH v3 00/10] learn the "reference" pretty format

[Denton Liu]

Hi all,

Thanks for the feedback from the last round. I've implemented it as a
canned user-format which reduces the amount of code we need to touch.
Thanks for the advice!


On this mailing list (and many others) the standard way to reference
other commits with the "reference" format, e.g. "f86a374 (pack-bitmap.c:
fix a memleak, 2015-03-30)". Since it's so commonly used, let's
standardise it as a pretty format.

Patches 5-7 were cleanup patches that were critical in earlier
iterations of the series but no longer are critical for the rest of the
patchset. Nonetheless, let's include them since they improve the quality
of the codebase.

Changes since v2:

* Rename from "summary" to "reference"

* Implement the feature as a canned userformat

* Implement the %*s (short date) format string element

* Remove the enclosing dqs around the subject

Changes since v1:

* Replace more references to "sha1" with "hash"

* Clean up 8/10 by losing the allocation and making the subject less
  misleading

* Add tests in 7/10 to ensure 8/10 does not change any behaviour

Denton Liu (9):
  SubmittingPatches: use generic terms for hash
  pretty-formats.txt: use generic terms for hash
  SubmittingPatches: remove dq from commit reference
  completion: complete `tformat:` pretty format
  revision: make get_revision_mark() return const pointer
  pretty.c: inline initalize format_context
  t4205: cover `git log --reflog -z` blindspot
  pretty: implement 'reference' format
  SubmittingPatches: use `--pretty=reference`

René Scharfe (1):
  pretty: provide short date format

 Documentation/SubmittingPatches        | 16 ++++--
 Documentation/pretty-formats.txt       | 28 +++++++---
 Documentation/pretty-options.txt       |  2 +-
 Documentation/rev-list-options.txt     |  4 +-
 contrib/completion/git-completion.bash |  2 +-
 pretty.c                               | 17 +++---
 revision.c                             |  4 +-
 revision.h                             |  4 +-
 t/t4205-log-pretty-formats.sh          | 72 ++++++++++++++++++++++++++
 9 files changed, 123 insertions(+), 26 deletions(-)

Range-diff against v2:
 1:  38a55e978f =  1:  5a9e19b37e SubmittingPatches: use generic terms for hash
 2:  9080b0db1f =  2:  4f2a9bef32 pretty-formats.txt: use generic terms for hash
 -:  ---------- >  3:  277d2b2506 SubmittingPatches: remove dq from commit reference
 -:  ---------- >  4:  442394eca8 completion: complete `tformat:` pretty format
 3:  1abab57072 =  5:  ca01bfa085 revision: make get_revision_mark() return const pointer
 4:  50ee13202c <  -:  ---------- revision: change abbrev_commit_given to abbrev_commit_explicit
 5:  45f0ceb476 !  6:  301e3adcdc pretty.c: inline initalize format_context
    @@ Commit message
         Instead of memsetting and then initializing the fields in the struct,
         move the initialization of `format_context` to its assignment.
     
    -    In preparation for a future commit where we mechanically move lines from
    -    repo_format_commit_message() into a helper function,
    -    `format_context.wrap_start` is not generically used so move its
    -    assignment closer to its use.
    -
         Signed-off-by: Denton Liu <liu.denton@gmail.com>
     
      ## pretty.c ##
    @@ pretty.c: void repo_format_commit_message(struct repository *r,
     -	struct format_commit_context context;
     +	struct format_commit_context context = {
     +		.commit = commit,
    -+		.pretty_ctx = pretty_ctx
    ++		.pretty_ctx = pretty_ctx,
    ++		.wrap_start = sb->len
     +	};
      	const char *output_enc = pretty_ctx->output_encoding;
      	const char *utf8 = "UTF-8";
    @@ pretty.c: void repo_format_commit_message(struct repository *r,
      	/*
      	 * convert a commit message to UTF-8 first
      	 * as far as 'format_commit_item' assumes it in UTF-8
    -@@ pretty.c: void repo_format_commit_message(struct repository *r,
    - 					       &context.commit_encoding,
    - 					       utf8);
    - 
    -+	context.wrap_start = sb->len;
    - 	strbuf_expand(sb, format, format_commit_item, &context);
    - 	rewrap_message_tail(sb, &context, 0, 0, 0);
    - 
 6:  e036a1a86d <  -:  ---------- pretty.c: extract functionality to repo_format_commit_generic()
 7:  7de6fe3282 !  7:  b1256c52ba t4205: cover `git log --reflog -z` blindspot
    @@ t/t4205-log-pretty-formats.sh: test_expect_failure C_LOCALE_OUTPUT 'NUL terminat
      	test_cmp expected actual
      '
      
    -+emit_nul () {
    -+	echo | tr '\n' '\000'
    -+}
    -+
     +for p in short medium full fuller email raw
     +do
     +	test_expect_success "NUL termination with --reflog --pretty=$p" '
    -+		>expect &&
     +		revs="$(git rev-list --reflog)" &&
     +		for r in $revs
     +		do
    -+			git show -s "$r" --pretty='$p' >>expect || return 1
    -+			emit_nul >>expect
    -+		done &&
    -+		git log -z --reflog --pretty='$p' >actual &&
    -+		emit_nul >>actual &&
    ++			git show -s "$r" --pretty="$p" &&
    ++			printf "\0" || return 1
    ++		done >expect &&
    ++		{
    ++			git log -z --reflog --pretty="$p" &&
    ++			printf "\0"
    ++		} >actual &&
     +		test_cmp expect actual
     +	'
     +done
     +
     +test_expect_success 'NUL termination with --reflog --pretty=oneline' '
    -+	>expect &&
     +	revs="$(git rev-list --reflog)" &&
     +	for r in $revs
     +	do
    -+		# trim trailing newline
    -+		output="$(git show -s --pretty=oneline "$r")" || return 1
    -+		printf "%s" "$output" >>expect
    -+		emit_nul >>expect
    -+	done &&
    ++		git show -s --pretty=oneline "$r" >raw &&
    ++		cat raw | lf_to_nul || exit 1
    ++	done >expect &&
    ++	# the trailing NUL is already produced so we do not need to
    ++	# output another one
     +	git log -z --pretty=oneline --reflog >actual &&
    -+	# no trailing NUL
     +	test_cmp expect actual
     +'
     +
 8:  3bda0f0ad7 <  -:  ---------- reflog-walk.c: move where the newline is added
 -:  ---------- >  8:  fe5cb165ae pretty: provide short date format
 9:  28c4f7f517 !  9:  470a2b0f4f pretty: implement 'summary' format
    @@ Metadata
     Author: Denton Liu <liu.denton@gmail.com>
     
      ## Commit message ##
    -    pretty: implement 'summary' format
    +    pretty: implement 'reference' format
     
         The standard format for referencing other commits within some projects
    -    (such as git.git) is the summary format. This is described in
    +    (such as git.git) is the reference format. This is described in
         Documentation/SubmittingPatches as
     
                 If you want to reference a previous commit in the history of a stable
    -            branch, use the format "abbreviated hash (subject, date)",
    -            with the subject enclosed in a pair of double-quotes, like this:
    +            branch, use the format "abbreviated hash (subject, date)", like this:
     
                 ....
    -                    Commit f86a374 ("pack-bitmap.c: fix a memleak", 2015-03-30)
    +                    Commit f86a374 (pack-bitmap.c: fix a memleak, 2015-03-30)
                         noticed that ...
                 ....
     
         Since this format is so commonly used, standardize it as a pretty
         format.
     
    -    This format is implemented as a separate flow that skips most of
    -    pretty_print_commit() and instead calls format_commit_summary(). The
    -    reason why this is done is because the other pretty formats expect
    -    output to be generated in a specific order. Specifically, the header,
    -    including the date, is always printed before the commit message,
    -    including the subject. Reversing the order would be possible but would
    -    involve butchering pretty_print_commit() so it is implemented as a
    -    separate flow.
    +    The tests that are implemented essentially show that the format-string
    +    does not change in response to various log options. This is useful
    +    because, for future developers, it shows that we've considered the
    +    limitations of the "canned format-string" approach and we are fine with
    +    them.
     
    +    Based-on-a-patch-by: SZEDER Gábor <szeder.dev@gmail.com>
         Signed-off-by: Denton Liu <liu.denton@gmail.com>
     
      ## Documentation/pretty-formats.txt ##
    @@ Documentation/pretty-formats.txt: This is designed to be as compact as possible.
      
      	       <full commit message>
      
    -+* 'summary'
    ++* 'reference'
     +
    -+	  <abbrev hash> ("<title line>", <short author date>)
    ++	  <abbrev hash> (<title line>, <short author date>)
     ++
     +This format is useful for referring to other commits when writing a new
    -+commit message. Although by default, '<abbrev hash>' is used, this can
    -+be overridden with '--no-abbrev'. In addition, '<short author date>' can
    -+be overridden by with '--date='.
    ++commit message. It uses the following canned user format:
    ++`%C(auto)%h (%s, %as)`. This means it will not respect options that
    ++change the output format such as `--date` `--no-abbrev-commit`, and
    ++`--walk-reflogs`.
     +
      * 'email'
      
    @@ Documentation/pretty-options.txt
      	Pretty-print the contents of the commit logs in a given format,
      	where '<format>' can be one of 'oneline', 'short', 'medium',
     -	'full', 'fuller', 'email', 'raw', 'format:<string>'
    -+	'full', 'fuller', 'summary', 'email', 'raw', 'format:<string>'
    ++	'full', 'fuller', 'reference', 'email', 'raw', 'format:<string>'
      	and 'tformat:<string>'.  When '<format>' is none of the above,
      	and has '%placeholder' in it, it acts as if
      	'--pretty=tformat:<format>' were given.
     
      ## Documentation/rev-list-options.txt ##
    -@@ Documentation/rev-list-options.txt: depending on a few rules:
    - 4. Otherwise, show the index format.
    - --
    +@@ Documentation/rev-list-options.txt: list.
    + 	exclude (that is, '{caret}commit', 'commit1..commit2',
    + 	and 'commit1\...commit2' notations cannot be used).
      +
    --Under `--pretty=oneline`, the commit message is
    -+Under `--pretty=oneline` and `--pretty=summary`, the commit message is
    +-With `--pretty` format other than `oneline` (for obvious reasons),
    ++With `--pretty` format other than `oneline` and `reference` (for obvious reasons),
    + this causes the output to have two extra lines of information
    + 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
    +@@ Documentation/rev-list-options.txt: 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].
    +++
    ++Under `--pretty=summary`, this information will not be shown at all.
    + 
    + --merge::
    + 	After a failed merge, show refs that touch files having a
     
    - ## builtin/log.c ##
    -@@ builtin/log.c: static void cmd_log_init_finish(int argc, const char **argv, const char *prefix,
    - 		read_mailmap(rev->mailmap, NULL);
    - 	}
    + ## contrib/completion/git-completion.bash ##
    +@@ contrib/completion/git-completion.bash: __git_log_shortlog_options="
    + 	--all-match --invert-grep
    + "
      
    --	if (rev->pretty_given && rev->commit_format == CMIT_FMT_RAW) {
    -+	if (rev->pretty_given) {
    -+		switch (rev->commit_format) {
    -+
    - 		/*
    - 		 * "log --pretty=raw" is special; ignore UI oriented
    - 		 * configuration variables such as decoration.
    - 		 */
    --		if (!decoration_given)
    --			decoration_style = 0;
    --		if (!rev->abbrev_commit_explicit)
    --			rev->abbrev_commit = 0;
    -+		case CMIT_FMT_RAW:
    -+			if (!decoration_given)
    -+				decoration_style = 0;
    -+			if (!rev->abbrev_commit_explicit)
    -+				rev->abbrev_commit = 0;
    -+			break;
    -+
    -+		/*
    -+		 * "log --pretty=summary" is special; ignore UI oriented
    -+		 * configuration variables such as decoration but keep
    -+		 * abbreviations.
    -+		 */
    -+		case CMIT_FMT_SUMMARY:
    -+			if (!decoration_given)
    -+				decoration_style = 0;
    -+			if (!rev->abbrev_commit_explicit)
    -+				rev->abbrev_commit = 1;
    -+			break;
    -+
    -+		default:
    -+			break;
    -+		}
    - 	}
    +-__git_log_pretty_formats="oneline short medium full fuller email raw format: tformat: mboxrd"
    ++__git_log_pretty_formats="oneline short medium full fuller reference email raw format: tformat: mboxrd"
    + __git_log_date_formats="relative iso8601 iso8601-strict rfc2822 short local default raw unix format:"
      
    - 	if (decoration_style) {
    -
    - ## log-tree.c ##
    -@@ log-tree.c: void show_log(struct rev_info *opt)
    - 		ctx.print_email_subject = 1;
    - 	} else if (opt->commit_format != CMIT_FMT_USERFORMAT) {
    - 		fputs(diff_get_color_opt(&opt->diffopt, DIFF_COMMIT), opt->diffopt.file);
    --		if (opt->commit_format != CMIT_FMT_ONELINE)
    -+		if (opt->commit_format != CMIT_FMT_ONELINE &&
    -+		    opt->commit_format != CMIT_FMT_SUMMARY)
    - 			fputs("commit ", opt->diffopt.file);
    - 
    - 		if (!opt->graph)
    -@@ log-tree.c: void show_log(struct rev_info *opt)
    - 			       find_unique_abbrev(&parent->object.oid, abbrev_commit));
    - 		fputs(diff_get_color_opt(&opt->diffopt, DIFF_RESET), opt->diffopt.file);
    - 		show_decorations(opt, commit);
    --		if (opt->commit_format == CMIT_FMT_ONELINE) {
    -+		if (opt->commit_format == CMIT_FMT_ONELINE ||
    -+		    opt->commit_format == CMIT_FMT_SUMMARY) {
    - 			putc(' ', opt->diffopt.file);
    - 		} else {
    - 			putc('\n', opt->diffopt.file);
    -@@ log-tree.c: void show_log(struct rev_info *opt)
    - 			 * graph info here.
    - 			 */
    - 			show_reflog_message(opt->reflog_info,
    --					    opt->commit_format == CMIT_FMT_ONELINE,
    -+					    (opt->commit_format == CMIT_FMT_ONELINE ||
    -+					     opt->commit_format == CMIT_FMT_SUMMARY),
    - 					    &opt->date_mode,
    - 					    opt->date_mode_explicit);
    - 			if (opt->commit_format == CMIT_FMT_ONELINE) {
    - 				putc('\n', opt->diffopt.file);
    - 				return;
    -+			} else if (opt->commit_format == CMIT_FMT_SUMMARY) {
    -+				putc(' ', opt->diffopt.file);
    - 			}
    - 		}
    - 	}
    + _git_log ()
     
      ## pretty.c ##
     @@ pretty.c: static void setup_commit_formats(void)
    @@ pretty.c: static void setup_commit_formats(void)
      		{ "full",	CMIT_FMT_FULL,		0,	8 },
     -		{ "oneline",	CMIT_FMT_ONELINE,	1,	0 }
     +		{ "oneline",	CMIT_FMT_ONELINE,	1,	0 },
    -+		{ "summary",	CMIT_FMT_SUMMARY,	1,	0 },
    ++		{ "reference",	CMIT_FMT_USERFORMAT,	1,	0,
    ++			0, "%C(auto)%h (%s, %as)" },
      		/*
      		 * Please update $__git_log_pretty_formats in
      		 * git-completion.bash when you add new formats.
    -@@ pretty.c: void repo_format_commit_message(struct repository *r,
    - 				   do_repo_format_commit_message, (void *)format);
    - }
    - 
    -+static void do_repo_format_commit_summary(struct strbuf *sb,
    -+					  struct format_commit_context *context,
    -+					  void *additional_context)
    -+{
    -+	struct ident_split ident;
    -+
    -+	parse_commit_header(context);
    -+	parse_commit_message(context);
    -+
    -+	strbuf_addstr(sb, "(\"");
    -+	format_subject(sb, context->message + context->subject_off, " ");
    -+	if (!split_ident_line(&ident,
    -+			      context->message + context->author.off,
    -+			      context->author.len)) {
    -+		strbuf_addstr(sb, "\", ");
    -+		strbuf_addstr(sb, show_ident_date(&ident, &context->pretty_ctx->date_mode));
    -+	}
    -+	strbuf_addstr(sb, ")");
    -+}
    -+
    - static void pp_header(struct pretty_print_context *pp,
    - 		      const char *encoding,
    - 		      const struct commit *commit,
    -@@ pretty.c: void pretty_print_commit(struct pretty_print_context *pp,
    - 		format_commit_message(commit, user_format, sb, pp);
    - 		return;
    - 	}
    -+	if (pp->fmt == CMIT_FMT_SUMMARY) {
    -+		if (!pp->date_mode_explicit)
    -+			pp->date_mode = *DATE_MODE(SHORT);
    -+
    -+		repo_format_commit_generic(the_repository, commit, sb, pp,
    -+					   do_repo_format_commit_summary, NULL);
    -+		return;
    -+	}
    - 
    - 	encoding = get_log_output_encoding();
    - 	msg = reencoded = logmsg_reencode(commit, NULL, encoding);
    -
    - ## pretty.h ##
    -@@ pretty.h: enum cmit_fmt {
    - 	CMIT_FMT_FULL,
    - 	CMIT_FMT_FULLER,
    - 	CMIT_FMT_ONELINE,
    -+	CMIT_FMT_SUMMARY,
    - 	CMIT_FMT_EMAIL,
    - 	CMIT_FMT_MBOXRD,
    - 	CMIT_FMT_USERFORMAT,
     
      ## t/t4205-log-pretty-formats.sh ##
    -@@ t/t4205-log-pretty-formats.sh: do
    - 	'
    - done
    - 
    --test_expect_success 'NUL termination with --reflog --pretty=oneline' '
    --	>expect &&
    --	revs="$(git rev-list --reflog)" &&
    --	for r in $revs
    --	do
    --		# trim trailing newline
    --		output="$(git show -s --pretty=oneline "$r")" || return 1
    --		printf "%s" "$output" >>expect
    --		emit_nul >>expect
    --	done &&
    --	git log -z --pretty=oneline --reflog >actual &&
    --	# no trailing NUL
    --	test_cmp expect actual
    --'
    -+for p in oneline summary
    -+do
    -+	test_expect_success "NUL termination with --reflog --pretty=$p" '
    -+		>expect &&
    -+		revs="$(git rev-list --reflog)" &&
    -+		for r in $revs
    -+		do
    -+			# trim trailing newline
    -+			output="$(git show -s --pretty='$p' "$r")" || return 1
    -+			printf "%s" "$output" >>expect
    -+			emit_nul >>expect
    -+		done &&
    -+		git log -z --pretty='$p' --reflog >actual &&
    -+		# no trailing NUL
    -+		test_cmp expect actual
    -+	'
    -+done
    - 
    - test_expect_success 'setup more commits' '
    - 	test_commit "message one" one one message-one &&
     @@ t/t4205-log-pretty-formats.sh: test_expect_success '%S in git log --format works with other placeholders (part
      	test_cmp expect actual
      '
      
    -+test_expect_success 'log --pretty=summary' '
    -+	git log --date=short --pretty="tformat:%h (\"%s\", %ad)" >expect &&
    -+	git log --pretty=summary >actual &&
    ++test_expect_success 'log --pretty=reference' '
    ++	git log --pretty="tformat:%h (%s, %as)" >expect &&
    ++	git log --pretty=reference >actual &&
     +	test_cmp expect actual
     +'
     +
    -+test_expect_success 'log --pretty=summary with log.date is overridden by short date' '
    -+	git log --date=short --pretty="tformat:%h (\"%s\", %ad)" >expect &&
    -+	test_config log.date rfc &&
    -+	git log --pretty=summary >actual &&
    ++test_expect_success 'log --pretty=reference always uses short date' '
    ++	git log --pretty="tformat:%h (%s, %as)" >expect &&
    ++	git log --date=rfc --pretty=reference >actual &&
     +	test_cmp expect actual
     +'
     +
    -+test_expect_success 'log --pretty=summary with explicit date overrides short date' '
    -+	git log --date=rfc --pretty="tformat:%h (\"%s\", %ad)" >expect &&
    -+	git log --date=rfc --pretty=summary >actual &&
    ++test_expect_success 'log --pretty=reference is never unabbreviated' '
    ++	git log --pretty="tformat:%h (%s, %as)" >expect &&
    ++	git log --no-abbrev-commit --pretty=reference >actual &&
     +	test_cmp expect actual
     +'
     +
    -+test_expect_success 'log --pretty=summary with log.abbrevCommit is overidden' '
    -+	git log --date=short --pretty="tformat:%h (\"%s\", %ad)" >expect &&
    -+	test_config log.abbrevCommit false &&
    -+	git log --pretty=summary >actual &&
    ++test_expect_success 'log --pretty=reference is never decorated' '
    ++	git log --pretty="tformat:%h (%s, %as)" >expect &&
    ++	git log --decorate=short --pretty=reference >actual &&
     +	test_cmp expect actual
     +'
     +
    -+test_expect_success 'log --pretty=summary with explicit --no-abbrev overrides abbreviated' '
    -+	git log --date=short --pretty="tformat:%H (\"%s\", %ad)" >expect &&
    -+	git log --no-abbrev --pretty=summary >actual &&
    ++test_expect_success 'log --pretty=reference does not output reflog info' '
    ++	git log --walk-reflogs --pretty="tformat:%h (%s, %as)" >expect &&
    ++	git log --walk-reflogs --pretty=reference >actual &&
     +	test_cmp expect actual
     +'
     +
    -+test_expect_success 'log --pretty=summary with log.decorate is overridden' '
    -+	git log --date=short --pretty="tformat:%h (\"%s\", %ad)" >expect &&
    -+	test_config log.decorate short &&
    -+	git log --pretty=summary >actual &&
    -+	test_cmp expect actual
    -+'
    -+
    -+test_expect_success 'log --pretty=summary with explicit decorate overrides no decoration' '
    -+	git log --date=short --pretty="tformat:%h%d (\"%s\", %ad)" >expect &&
    -+	git log --decorate=short --pretty=summary >actual &&
    -+	test_cmp expect actual
    -+'
    -+
    -+test_expect_success 'log --pretty=summary with --walk-reflogs' '
    -+	test_config log.date short &&
    -+	git log --walk-reflogs --pretty="tformat:%h %gd: %gs (\"%s\", %ad)" >expect &&
    -+	git log --walk-reflogs --pretty=summary >actual &&
    ++test_expect_success 'log --pretty=reference is colored appropriately' '
    ++	git log --color=always --pretty="tformat:%C(auto)%h (%s, %as)" >expect &&
    ++	git log --color=always --pretty=reference >actual &&
     +	test_cmp expect actual
     +'
     +
10:  a6638f0c7c ! 10:  5f80e4633d SubmittingPatches: use `--pretty=summary`
    @@ Metadata
     Author: Denton Liu <liu.denton@gmail.com>
     
      ## Commit message ##
    -    SubmittingPatches: use `--pretty=summary`
    +    SubmittingPatches: use `--pretty=reference`
     
    -    Since Git was taught the `--pretty=summary` option, it is no longer
    +    Since Git was taught the `--pretty=reference` option, it is no longer
         necessary to manually specify the format string to get the commit
    -    summary. Teach users to use the new option while keeping the old
    +    reference. Teach users to use the new option while keeping the old
         invocation around in case they have an older version of Git.
     
         Signed-off-by: Denton Liu <liu.denton@gmail.com>
     
      ## Documentation/SubmittingPatches ##
    -@@ Documentation/SubmittingPatches: with the subject enclosed in a pair of double-quotes, like this:
    - The "Copy commit summary" command of gitk can be used to obtain this
    - format, or this invocation of `git show`:
    +@@ Documentation/SubmittingPatches: The "Copy commit summary" command of gitk can be used to obtain this
    + format (with the subject enclosed in a pair of double-quotes), or this
    + invocation of `git show`:
      
     +....
    -+	git show -s --pretty=summary <commit>
    ++	git show -s --pretty=reference <commit>
     +....
     +
    -+or, on an older version of Git without support for --pretty=summary:
    ++or, on an older version of Git without support for --pretty=reference:
     +
      ....
    - 	git show -s --date=short --pretty='format:%h ("%s", %ad)' <commit>
    + 	git show -s --date=short --pretty='format:%h (%s, %ad)' <commit>
      ....
-- 
2.24.0.346.gee0de6d492

[PATCH v3 01/10] SubmittingPatches: use generic terms for hash

[Denton Liu]

Since Git is planning on upgrading from SHA-1 to be more hash-agnostic,
replace specific references to SHA-1 with more generic terminology.

Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
 Documentation/SubmittingPatches | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 1a60cc1329..bb7e33ce15 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -142,7 +142,7 @@ archive, summarize the relevant points of the discussion.
 
 [[commit-reference]]
 If you want to reference a previous commit in the history of a stable
-branch, use the format "abbreviated sha1 (subject, date)",
+branch, use the format "abbreviated hash (subject, date)",
 with the subject enclosed in a pair of double-quotes, like this:
 
 ....
-- 
2.24.0.346.gee0de6d492

[PATCH v3 02/10] pretty-formats.txt: use generic terms for hash

[Denton Liu]

Since Git is planning on upgrading from SHA-1 to be more hash-agnostic,
replace specific references to SHA-1 with more generic terminology.

Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
 Documentation/pretty-formats.txt | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt
index 31c6e8d2b8..4cefa64eeb 100644
--- a/Documentation/pretty-formats.txt
+++ b/Documentation/pretty-formats.txt
@@ -4,7 +4,7 @@ PRETTY FORMATS
 If the commit is a merge, and if the pretty-format
 is not 'oneline', 'email' or 'raw', an additional line is
 inserted before the 'Author:' line.  This line begins with
-"Merge: " and the sha1s of ancestral commits are printed,
+"Merge: " and the hashes of ancestral commits are printed,
 separated by spaces.  Note that the listed commits may not
 necessarily be the list of the *direct* parent commits if you
 have limited your view of history: for example, if you are
@@ -20,20 +20,20 @@ built-in formats:
 
 * 'oneline'
 
-	  <sha1> <title line>
+	  <hash> <title line>
 +
 This is designed to be as compact as possible.
 
 * 'short'
 
-	  commit <sha1>
+	  commit <hash>
 	  Author: <author>
 
 	      <title line>
 
 * 'medium'
 
-	  commit <sha1>
+	  commit <hash>
 	  Author: <author>
 	  Date:   <author date>
 
@@ -43,7 +43,7 @@ This is designed to be as compact as possible.
 
 * 'full'
 
-	  commit <sha1>
+	  commit <hash>
 	  Author: <author>
 	  Commit: <committer>
 
@@ -53,7 +53,7 @@ This is designed to be as compact as possible.
 
 * 'fuller'
 
-	  commit <sha1>
+	  commit <hash>
 	  Author:     <author>
 	  AuthorDate: <author date>
 	  Commit:     <committer>
@@ -65,7 +65,7 @@ This is designed to be as compact as possible.
 
 * 'email'
 
-	  From <sha1> <date>
+	  From <hash> <date>
 	  From: <author>
 	  Date: <author date>
 	  Subject: [PATCH] <title line>
@@ -75,7 +75,7 @@ This is designed to be as compact as possible.
 * 'raw'
 +
 The 'raw' format shows the entire commit exactly as
-stored in the commit object.  Notably, the SHA-1s are
+stored in the commit object.  Notably, the hashes are
 displayed in full, regardless of whether --abbrev or
 --no-abbrev are used, and 'parents' information show the
 true parent commits, without taking grafts or history
-- 
2.24.0.346.gee0de6d492

[PATCH v3 03/10] SubmittingPatches: remove dq from commit reference

[Denton Liu]

Quoting SZEDER Gábor[1],

	SubmittingPatches is simply wrong: our de-facto standard format for
	referencing other commits does not enclose the subject in a pair of
	double-quotes:

	  $ git log v2.24.0 |grep -E '[0-9a-f]{7} \("' |wc -l
	  785
	  $ git log v2.24.0 |grep -E '[0-9a-f]{7} \([^"]' |wc -l
	  2276

	Those double-quotes don't add any value to the references, but they
	result in weird looking references for 1083 of our commits whose
	subject lines happen to end with double-quotes, e.g.:

	  f23a465132 ("hashmap_get{,_from_hash} return "struct hashmap_entry *"", 2019-10-06)

	and without those unnecessary pair of double-quotes we would have
	~3000 more commits whose summary would fit on a single line.

Remove references to the enclosing double-quotes from SubmittingPatches
since our de-facto standard for referencing commits does not actually
use them.

[1]: cf. <20191114011048.GS4348@szeder.dev>

Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
 Documentation/SubmittingPatches | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index bb7e33ce15..7860dd2568 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -142,19 +142,19 @@ archive, summarize the relevant points of the discussion.
 
 [[commit-reference]]
 If you want to reference a previous commit in the history of a stable
-branch, use the format "abbreviated hash (subject, date)",
-with the subject enclosed in a pair of double-quotes, like this:
+branch, use the format "abbreviated hash (subject, date)", like this:
 
 ....
-	Commit f86a374 ("pack-bitmap.c: fix a memleak", 2015-03-30)
+	Commit f86a374 (pack-bitmap.c: fix a memleak, 2015-03-30)
 	noticed that ...
 ....
 
 The "Copy commit summary" command of gitk can be used to obtain this
-format, or this invocation of `git show`:
+format (with the subject enclosed in a pair of double-quotes), or this
+invocation of `git show`:
 
 ....
-	git show -s --date=short --pretty='format:%h ("%s", %ad)' <commit>
+	git show -s --date=short --pretty='format:%h (%s, %ad)' <commit>
 ....
 
 [[git-tools]]
-- 
2.24.0.346.gee0de6d492

[PATCH v3 04/10] completion: complete `tformat:` pretty format

[Denton Liu]

Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
 contrib/completion/git-completion.bash | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/contrib/completion/git-completion.bash b/contrib/completion/git-completion.bash
index 00fbe6c03d..557d0373c3 100644
--- a/contrib/completion/git-completion.bash
+++ b/contrib/completion/git-completion.bash
@@ -1749,7 +1749,7 @@ __git_log_shortlog_options="
 	--all-match --invert-grep
 "
 
-__git_log_pretty_formats="oneline short medium full fuller email raw format: mboxrd"
+__git_log_pretty_formats="oneline short medium full fuller email raw format: tformat: mboxrd"
 __git_log_date_formats="relative iso8601 iso8601-strict rfc2822 short local default raw unix format:"
 
 _git_log ()
-- 
2.24.0.346.gee0de6d492

[PATCH v3 05/10] revision: make get_revision_mark() return const pointer

[Denton Liu]

get_revision_mark() used to return a `char *`, even though all of the
strings it was returning were string literals. Make get_revision_mark()
return a `const char *` so that callers won't be tempted to modify the
returned string.

Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
 revision.c | 4 ++--
 revision.h | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/revision.c b/revision.c
index 0e39b2b8a5..2151b119b7 100644
--- a/revision.c
+++ b/revision.c
@@ -3944,7 +3944,7 @@ struct commit *get_revision(struct rev_info *revs)
 	return c;
 }
 
-char *get_revision_mark(const struct rev_info *revs, const struct commit *commit)
+const char *get_revision_mark(const struct rev_info *revs, const struct commit *commit)
 {
 	if (commit->object.flags & BOUNDARY)
 		return "-";
@@ -3966,7 +3966,7 @@ char *get_revision_mark(const struct rev_info *revs, const struct commit *commit
 
 void put_revision_mark(const struct rev_info *revs, const struct commit *commit)
 {
-	char *mark = get_revision_mark(revs, commit);
+	const char *mark = get_revision_mark(revs, commit);
 	if (!strlen(mark))
 		return;
 	fputs(mark, stdout);
diff --git a/revision.h b/revision.h
index 4134dc6029..addd69410b 100644
--- a/revision.h
+++ b/revision.h
@@ -322,8 +322,8 @@ int handle_revision_arg(const char *arg, struct rev_info *revs,
 void reset_revision_walk(void);
 int prepare_revision_walk(struct rev_info *revs);
 struct commit *get_revision(struct rev_info *revs);
-char *get_revision_mark(const struct rev_info *revs,
-			const struct commit *commit);
+const char *get_revision_mark(const struct rev_info *revs,
+			      const struct commit *commit);
 void put_revision_mark(const struct rev_info *revs,
 		       const struct commit *commit);
 
-- 
2.24.0.346.gee0de6d492

[PATCH v3 06/10] pretty.c: inline initalize format_context

[Denton Liu]

Instead of memsetting and then initializing the fields in the struct,
move the initialization of `format_context` to its assignment.

Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
 pretty.c | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/pretty.c b/pretty.c
index 93eb6e8370..4d633f14fa 100644
--- a/pretty.c
+++ b/pretty.c
@@ -1617,14 +1617,14 @@ void repo_format_commit_message(struct repository *r,
 				const char *format, struct strbuf *sb,
 				const struct pretty_print_context *pretty_ctx)
 {
-	struct format_commit_context context;
+	struct format_commit_context context = {
+		.commit = commit,
+		.pretty_ctx = pretty_ctx,
+		.wrap_start = sb->len
+	};
 	const char *output_enc = pretty_ctx->output_encoding;
 	const char *utf8 = "UTF-8";
 
-	memset(&context, 0, sizeof(context));
-	context.commit = commit;
-	context.pretty_ctx = pretty_ctx;
-	context.wrap_start = sb->len;
 	/*
 	 * convert a commit message to UTF-8 first
 	 * as far as 'format_commit_item' assumes it in UTF-8
-- 
2.24.0.346.gee0de6d492

[PATCH v3 07/10] t4205: cover `git log --reflog -z` blindspot

[Denton Liu]

The test suite does not include any tests where `--reflog` and `-z` are
used together in `git log`. Cover this blindspot. Note that the
`--pretty=oneline` case is written separately because it follows a
slightly different codepath.

Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
 t/t4205-log-pretty-formats.sh | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/t/t4205-log-pretty-formats.sh b/t/t4205-log-pretty-formats.sh
index f42a69faa2..0335b428b1 100755
--- a/t/t4205-log-pretty-formats.sh
+++ b/t/t4205-log-pretty-formats.sh
@@ -134,6 +134,36 @@ test_expect_failure C_LOCALE_OUTPUT 'NUL termination with --stat' '
 	test_cmp expected actual
 '
 
+for p in short medium full fuller email raw
+do
+	test_expect_success "NUL termination with --reflog --pretty=$p" '
+		revs="$(git rev-list --reflog)" &&
+		for r in $revs
+		do
+			git show -s "$r" --pretty="$p" &&
+			printf "\0" || return 1
+		done >expect &&
+		{
+			git log -z --reflog --pretty="$p" &&
+			printf "\0"
+		} >actual &&
+		test_cmp expect actual
+	'
+done
+
+test_expect_success 'NUL termination with --reflog --pretty=oneline' '
+	revs="$(git rev-list --reflog)" &&
+	for r in $revs
+	do
+		git show -s --pretty=oneline "$r" >raw &&
+		cat raw | lf_to_nul || exit 1
+	done >expect &&
+	# the trailing NUL is already produced so we do not need to
+	# output another one
+	git log -z --pretty=oneline --reflog >actual &&
+	test_cmp expect actual
+'
+
 test_expect_success 'setup more commits' '
 	test_commit "message one" one one message-one &&
 	test_commit "message two" two two message-two &&
-- 
2.24.0.346.gee0de6d492

[PATCH v3 08/10] pretty: provide short date format

[Denton Liu]

From: René Scharfe <l.s.r@web.de>

Add the placeholders %as and %cs to format author date and committer
date, respectively, without the time part, like --date=short does, i.e.
like YYYY-MM-DD.

Signed-off-by: René Scharfe <l.s.r@web.de>
Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
 Documentation/pretty-formats.txt | 2 ++
 pretty.c                         | 3 +++
 t/t4205-log-pretty-formats.sh    | 6 ++++++
 3 files changed, 11 insertions(+)

diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt
index 4cefa64eeb..11979301ff 100644
--- a/Documentation/pretty-formats.txt
+++ b/Documentation/pretty-formats.txt
@@ -172,6 +172,7 @@ The placeholders are:
 '%at':: author date, UNIX timestamp
 '%ai':: author date, ISO 8601-like format
 '%aI':: author date, strict ISO 8601 format
+'%as':: author date, short format (`YYYY-MM-DD`)
 '%cn':: committer name
 '%cN':: committer name (respecting .mailmap, see
 	linkgit:git-shortlog[1] or linkgit:git-blame[1])
@@ -187,6 +188,7 @@ The placeholders are:
 '%ct':: committer date, UNIX timestamp
 '%ci':: committer date, ISO 8601-like format
 '%cI':: committer date, strict ISO 8601 format
+'%cs':: committer date, short format (`YYYY-MM-DD`)
 '%d':: ref names, like the --decorate option of linkgit:git-log[1]
 '%D':: ref names without the " (", ")" wrapping.
 '%S':: ref name given on the command line by which the commit was reached
diff --git a/pretty.c b/pretty.c
index 4d633f14fa..4d7f5e9aab 100644
--- a/pretty.c
+++ b/pretty.c
@@ -738,6 +738,9 @@ static size_t format_person_part(struct strbuf *sb, char part,
 	case 'I':	/* date, ISO 8601 strict */
 		strbuf_addstr(sb, show_ident_date(&s, DATE_MODE(ISO8601_STRICT)));
 		return placeholder_len;
+	case 's':
+		strbuf_addstr(sb, show_ident_date(&s, DATE_MODE(SHORT)));
+		return placeholder_len;
 	}
 
 skip:
diff --git a/t/t4205-log-pretty-formats.sh b/t/t4205-log-pretty-formats.sh
index 0335b428b1..da9cacffea 100755
--- a/t/t4205-log-pretty-formats.sh
+++ b/t/t4205-log-pretty-formats.sh
@@ -533,6 +533,12 @@ test_expect_success 'ISO and ISO-strict date formats display the same values' '
 	test_cmp expected actual
 '
 
+test_expect_success 'short date' '
+	git log --format=%ad%n%cd --date=short >expected &&
+	git log --format=%as%n%cs >actual &&
+	test_cmp expected actual
+'
+
 # get new digests (with no abbreviations)
 test_expect_success 'set up log decoration tests' '
 	head1=$(git rev-parse --verify HEAD~0) &&
-- 
2.24.0.346.gee0de6d492

[PATCH v3 09/10] pretty: implement 'reference' format

[Denton Liu]

The standard format for referencing other commits within some projects
(such as git.git) is the reference format. This is described in
Documentation/SubmittingPatches as

	If you want to reference a previous commit in the history of a stable
	branch, use the format "abbreviated hash (subject, date)", like this:

	....
		Commit f86a374 (pack-bitmap.c: fix a memleak, 2015-03-30)
		noticed that ...
	....

Since this format is so commonly used, standardize it as a pretty
format.

The tests that are implemented essentially show that the format-string
does not change in response to various log options. This is useful
because, for future developers, it shows that we've considered the
limitations of the "canned format-string" approach and we are fine with
them.

Based-on-a-patch-by: SZEDER Gábor <szeder.dev@gmail.com>
Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
 Documentation/pretty-formats.txt       | 10 +++++++
 Documentation/pretty-options.txt       |  2 +-
 Documentation/rev-list-options.txt     |  4 ++-
 contrib/completion/git-completion.bash |  2 +-
 pretty.c                               |  4 ++-
 t/t4205-log-pretty-formats.sh          | 36 ++++++++++++++++++++++++++
 6 files changed, 54 insertions(+), 4 deletions(-)

diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt
index 11979301ff..ee1a945bae 100644
--- a/Documentation/pretty-formats.txt
+++ b/Documentation/pretty-formats.txt
@@ -63,6 +63,16 @@ This is designed to be as compact as possible.
 
 	       <full commit message>
 
+* 'reference'
+
+	  <abbrev hash> (<title line>, <short author date>)
++
+This format is useful for referring to other commits when writing a new
+commit message. It uses the following canned user format:
+`%C(auto)%h (%s, %as)`. This means it will not respect options that
+change the output format such as `--date` `--no-abbrev-commit`, and
+`--walk-reflogs`.
+
 * 'email'
 
 	  From <hash> <date>
diff --git a/Documentation/pretty-options.txt b/Documentation/pretty-options.txt
index e44fc8f738..a59426eefd 100644
--- a/Documentation/pretty-options.txt
+++ b/Documentation/pretty-options.txt
@@ -3,7 +3,7 @@
 
 	Pretty-print the contents of the commit logs in a given format,
 	where '<format>' can be one of 'oneline', 'short', 'medium',
-	'full', 'fuller', 'email', 'raw', 'format:<string>'
+	'full', 'fuller', 'reference', 'email', 'raw', 'format:<string>'
 	and 'tformat:<string>'.  When '<format>' is none of the above,
 	and has '%placeholder' in it, it acts as if
 	'--pretty=tformat:<format>' were given.
diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
index 90ff9e2bea..91edeaf6d5 100644
--- a/Documentation/rev-list-options.txt
+++ b/Documentation/rev-list-options.txt
@@ -269,7 +269,7 @@ list.
 	exclude (that is, '{caret}commit', 'commit1..commit2',
 	and 'commit1\...commit2' notations cannot be used).
 +
-With `--pretty` format other than `oneline` (for obvious reasons),
+With `--pretty` format other than `oneline` and `reference` (for obvious reasons),
 this causes the output to have two extra lines of information
 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
@@ -293,6 +293,8 @@ 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].
++
+Under `--pretty=summary`, this information will not be shown at all.
 
 --merge::
 	After a failed merge, show refs that touch files having a
diff --git a/contrib/completion/git-completion.bash b/contrib/completion/git-completion.bash
index 557d0373c3..007e6a06d6 100644
--- a/contrib/completion/git-completion.bash
+++ b/contrib/completion/git-completion.bash
@@ -1749,7 +1749,7 @@ __git_log_shortlog_options="
 	--all-match --invert-grep
 "
 
-__git_log_pretty_formats="oneline short medium full fuller email raw format: tformat: mboxrd"
+__git_log_pretty_formats="oneline short medium full fuller reference email raw format: tformat: mboxrd"
 __git_log_date_formats="relative iso8601 iso8601-strict rfc2822 short local default raw unix format:"
 
 _git_log ()
diff --git a/pretty.c b/pretty.c
index 4d7f5e9aab..88a3bc621d 100644
--- a/pretty.c
+++ b/pretty.c
@@ -97,7 +97,9 @@ static void setup_commit_formats(void)
 		{ "mboxrd",	CMIT_FMT_MBOXRD,	0,	0 },
 		{ "fuller",	CMIT_FMT_FULLER,	0,	8 },
 		{ "full",	CMIT_FMT_FULL,		0,	8 },
-		{ "oneline",	CMIT_FMT_ONELINE,	1,	0 }
+		{ "oneline",	CMIT_FMT_ONELINE,	1,	0 },
+		{ "reference",	CMIT_FMT_USERFORMAT,	1,	0,
+			0, "%C(auto)%h (%s, %as)" },
 		/*
 		 * Please update $__git_log_pretty_formats in
 		 * git-completion.bash when you add new formats.
diff --git a/t/t4205-log-pretty-formats.sh b/t/t4205-log-pretty-formats.sh
index da9cacffea..9a9a18f104 100755
--- a/t/t4205-log-pretty-formats.sh
+++ b/t/t4205-log-pretty-formats.sh
@@ -824,4 +824,40 @@ test_expect_success '%S in git log --format works with other placeholders (part
 	test_cmp expect actual
 '
 
+test_expect_success 'log --pretty=reference' '
+	git log --pretty="tformat:%h (%s, %as)" >expect &&
+	git log --pretty=reference >actual &&
+	test_cmp expect actual
+'
+
+test_expect_success 'log --pretty=reference always uses short date' '
+	git log --pretty="tformat:%h (%s, %as)" >expect &&
+	git log --date=rfc --pretty=reference >actual &&
+	test_cmp expect actual
+'
+
+test_expect_success 'log --pretty=reference is never unabbreviated' '
+	git log --pretty="tformat:%h (%s, %as)" >expect &&
+	git log --no-abbrev-commit --pretty=reference >actual &&
+	test_cmp expect actual
+'
+
+test_expect_success 'log --pretty=reference is never decorated' '
+	git log --pretty="tformat:%h (%s, %as)" >expect &&
+	git log --decorate=short --pretty=reference >actual &&
+	test_cmp expect actual
+'
+
+test_expect_success 'log --pretty=reference does not output reflog info' '
+	git log --walk-reflogs --pretty="tformat:%h (%s, %as)" >expect &&
+	git log --walk-reflogs --pretty=reference >actual &&
+	test_cmp expect actual
+'
+
+test_expect_success 'log --pretty=reference is colored appropriately' '
+	git log --color=always --pretty="tformat:%C(auto)%h (%s, %as)" >expect &&
+	git log --color=always --pretty=reference >actual &&
+	test_cmp expect actual
+'
+
 test_done
-- 
2.24.0.346.gee0de6d492

[PATCH v3 10/10] SubmittingPatches: use `--pretty=reference`

[Denton Liu]

Since Git was taught the `--pretty=reference` option, it is no longer
necessary to manually specify the format string to get the commit
reference. Teach users to use the new option while keeping the old
invocation around in case they have an older version of Git.

Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
 Documentation/SubmittingPatches | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 7860dd2568..4515cab519 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -153,6 +153,12 @@ The "Copy commit summary" command of gitk can be used to obtain this
 format (with the subject enclosed in a pair of double-quotes), or this
 invocation of `git show`:
 
+....
+	git show -s --pretty=reference <commit>
+....
+
+or, on an older version of Git without support for --pretty=reference:
+
 ....
 	git show -s --date=short --pretty='format:%h (%s, %ad)' <commit>
 ....
-- 
2.24.0.346.gee0de6d492

Re: [PATCH v3 09/10] pretty: implement 'reference' format

[Todd Zullinger]

Denton Liu wrote:
> index 90ff9e2bea..91edeaf6d5 100644
> --- a/Documentation/rev-list-options.txt
> +++ b/Documentation/rev-list-options.txt
> @@ -269,7 +269,7 @@ list.
>  	exclude (that is, '{caret}commit', 'commit1..commit2',
>  	and 'commit1\...commit2' notations cannot be used).
>  +
> -With `--pretty` format other than `oneline` (for obvious reasons),
> +With `--pretty` format other than `oneline` and `reference` (for obvious reasons),
>  this causes the output to have two extra lines of information
>  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
> @@ -293,6 +293,8 @@ 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].
> ++
> +Under `--pretty=summary`, this information will not be shown at all.

I think the line above wants s/summary/reference.

-- 
Todd

Re: [PATCH v3 09/10] pretty: implement 'reference' format

[Junio C Hamano]

Denton Liu <liu.denton@gmail.com> writes:

> +* 'reference'
> +
> +	  <abbrev hash> (<title line>, <short author date>)

s/title line/title/ as you definitely do *not* want a line with a
title on it (and nothing else) in this context.

> +This format is useful for referring to other commits when writing a new
> +commit message. It uses the following canned user format:
> +`%C(auto)%h (%s, %as)`. This means it will not respect options that
> +change the output format such as `--date` `--no-abbrev-commit`, and
> +`--walk-reflogs`.

Ignoring of the '--date' may want to be eventually fixed, but for an
initial cut, using %as in the canned format is a good approach for
expediency.

I thought that %h can be told to give arbitrary long hash with
--abbrev=<n>, up to n==40 (or the number of bytes the hash of your
choice has), so I am not sure if `--no-abbrev-commit` is worth
mentioning.  I do not think I understand what you wanted to do by
using `--walk-reflogs` with the format at all, either.

Thanks.

Re: [PATCH v3 09/10] pretty: implement 'reference' format

[Eric Sunshine]

On Thu, Nov 14, 2019 at 3:47 PM Denton Liu <liu.denton@gmail.com> wrote:
> [...]
> Since this format is so commonly used, standardize it as a pretty
> format.
> [...]
> Signed-off-by: Denton Liu <liu.denton@gmail.com>
> ---
> diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt
> @@ -63,6 +63,16 @@ This is designed to be as compact as possible.
> +This format is useful for referring to other commits when writing a new
> +commit message. It uses the following canned user format:
> +`%C(auto)%h (%s, %as)`. This means it will not respect options that
> +change the output format such as `--date` `--no-abbrev-commit`, and
> +`--walk-reflogs`.

Missing comma between `--date` and `--no-abbrev-commit`.

Re: [PATCH v3 09/10] pretty: implement 'reference' format

[SZEDER Gábor]

On Fri, Nov 15, 2019 at 03:07:59PM +0900, Junio C Hamano wrote:
> Denton Liu <liu.denton@gmail.com> writes:
> 
> > +* 'reference'
> > +
> > +	  <abbrev hash> (<title line>, <short author date>)
> 
> s/title line/title/ as you definitely do *not* want a line with a
> title on it (and nothing else) in this context.

Well, we just followed suit of the descriptions of other pretty
formats, and they all say "<title line>".

On a related note, the description of the '%s' format specifier in the
same document is "subject", not "title".  Perhaps they should be made
consistent, but I'm not sure.  I like that '%s' means "subject",
because the first letter matches, but some man pages (commit,
format-patch, am) make difference between a subject and a title.

Re: [PATCH v3 09/10] pretty: implement 'reference' format

[Junio C Hamano]

SZEDER Gábor <szeder.dev@gmail.com> writes:

> On Fri, Nov 15, 2019 at 03:07:59PM +0900, Junio C Hamano wrote:
>> Denton Liu <liu.denton@gmail.com> writes:
>> 
>> > +* 'reference'
>> > +
>> > +	  <abbrev hash> (<title line>, <short author date>)
>> 
>> s/title line/title/ as you definitely do *not* want a line with a
>> title on it (and nothing else) in this context.
>
> Well, we just followed suit of the descriptions of other pretty
> formats, and they all say "<title line>".
>
> On a related note, the description of the '%s' format specifier in the
> same document is "subject", not "title".  Perhaps they should be made
> consistent, but I'm not sure.  I like that '%s' means "subject",
> because the first letter matches, but some man pages (commit,
> format-patch, am) make difference between a subject and a title.

Yeah, I think these are used more or less interchangeably, and we
may want to clarify the distinction.  Between the two, <title> is a
more appropriate "context neutral" name for the thing, i.e. one line
(technically, one paragraph) summary of what the commit is about.
Where <subject> becomes more relevant is when a commit is expressed
as a piece of patch e-mail, where <title> is used on the "Subject: "
header.

Thanks.

Re: [PATCH v3 09/10] pretty: implement 'reference' format

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

> Denton Liu <liu.denton@gmail.com> writes:
>
>> +* 'reference'
>> +
>> +	  <abbrev hash> (<title line>, <short author date>)
>
> s/title line/title/ as you definitely do *not* want a line with a
> title on it (and nothing else) in this context.
>
>> +This format is useful for referring to other commits when writing a new
>> +commit message. It uses the following canned user format:
>> +`%C(auto)%h (%s, %as)`. This means it will not respect options that
>> +change the output format such as `--date` `--no-abbrev-commit`, and
>> +`--walk-reflogs`.
>
> Ignoring of the '--date' may want to be eventually fixed, but for an
> initial cut, using %as in the canned format is a good approach for
> expediency.
> ...
> ...  I do not think I understand what you wanted to do by
> using `--walk-reflogs` with the format at all, either.

OK, I re-read the patch text and I understand what you wanted to
say.  The mention of --walk-reflogs in the new description is
grossly misleading.

   $ git log --pretty=ref --walk-reflogs @{now}

would work perfectly fine.  It is an instruction that tells "git
log" not to follow the commit ancestry from the commit that sits at
the current branch right now, but instead follow the history of what
commits used to sit at the tip of the current branch.

"--pretty=format:<anything>" overrides only the side effect of
"--walk-reflogs" that modifies traditional built-in formats.  But
the above makes it sound as if use of "--pretty=ref" somehow makes
our commands to ignore the entire effect of any option that has side
effect of changing the output format, which is not true.

The `--date` and `--decorate` options would be a good example of
options "that change the output format".  If you want to mention the
effect of this option on the `--walk-reflogs` option correctly, the
explanation must make sure that only the output aspect is affected.

Perhaps like this

	This format is used to refer another commit in a commit
	message as "<short hash> (<title>, <author date>)" and is
	the same as `--pretty=format:%C(auto)%h (%s, %as)`.  As with
	any `format:` with format placeholders, its output is not
	affected by other options like `--decorate` and
	`--walk-reflogs`.

I guess?

We would want to fix it in such a way that it uses %ad instead of
%as, but internally tweak the default date format to short unless
the --date option is given.

Thanks.

Re: [PATCH v3 09/10] pretty: implement 'reference' format

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

> SZEDER Gábor <szeder.dev@gmail.com> writes:
>
>> On Fri, Nov 15, 2019 at 03:07:59PM +0900, Junio C Hamano wrote:
>>> Denton Liu <liu.denton@gmail.com> writes:
>>> 
>>> > +* 'reference'
>>> > +
>>> > +	  <abbrev hash> (<title line>, <short author date>)
>>> 
>>> s/title line/title/ as you definitely do *not* want a line with a
>>> title on it (and nothing else) in this context.
>>
>> Well, we just followed suit of the descriptions of other pretty
>> formats, and they all say "<title line>".

Sorry I failed to respond to this point.  I think it is OK to leave
it <title line> in this series, then.  Updating them need to be done
for all at once together with other formats.

Thanks.

[PATCH v4 00/11] learn the "reference" pretty format

[Denton Liu]

On this mailing list (and many others) the standard way to reference
other commits with the "reference" format, e.g. "f86a374 (pack-bitmap.c:
fix a memleak, 2015-03-30)". Since it's so commonly used, let's
standardise it as a pretty format.

Patches 5-7 were cleanup patches that were critical in earlier
iterations of the series but no longer are critical for the rest of the
patchset. Nonetheless, let's include them since they improve the quality
of the codebase.

Changes since v3:

* Change one reference from "summary" to "reference"

* Clarify --pretty=reference documentation

* Add a squashable patch at the end to implement overridable --date

Changes since v2:

* Rename from "summary" to "reference"

* Implement the feature as a canned userformat

* Implement the %*s (short date) format string element

* Remove the enclosing dqs around the subject

Changes since v1:

* Replace more references to "sha1" with "hash"

* Clean up 8/10 by losing the allocation and making the subject less
  misleading

* Add tests in 7/10 to ensure 8/10 does not change any behaviour

Denton Liu (10):
  SubmittingPatches: use generic terms for hash
  pretty-formats.txt: use generic terms for hash
  SubmittingPatches: remove dq from commit reference
  completion: complete `tformat:` pretty format
  revision: make get_revision_mark() return const pointer
  pretty.c: inline initalize format_context
  t4205: cover `git log --reflog -z` blindspot
  pretty: implement 'reference' format
  SubmittingPatches: use `--pretty=reference`
  squash! pretty: implement 'reference' format

René Scharfe (1):
  pretty: provide short date format

 Documentation/SubmittingPatches        | 16 ++++--
 Documentation/pretty-formats.txt       | 29 +++++++---
 Documentation/pretty-options.txt       |  2 +-
 Documentation/rev-list-options.txt     |  4 +-
 contrib/completion/git-completion.bash |  2 +-
 pretty.c                               | 23 ++++++--
 revision.c                             |  4 +-
 revision.h                             |  4 +-
 t/t4205-log-pretty-formats.sh          | 79 ++++++++++++++++++++++++++
 9 files changed, 137 insertions(+), 26 deletions(-)

Range-diff against v3:
 1:  d0f0b86f5f =  1:  3b9b72feec SubmittingPatches: use generic terms for hash
 2:  aabd7574d2 =  2:  2cc7cc6e75 pretty-formats.txt: use generic terms for hash
 3:  ef0adc260d =  3:  61e1a25f93 SubmittingPatches: remove dq from commit reference
 4:  d7e4dc9154 =  4:  5d9fd9d632 completion: complete `tformat:` pretty format
 5:  cc219ec513 =  5:  bfb216954b revision: make get_revision_mark() return const pointer
 6:  883517ee65 =  6:  34e1b6a7ac pretty.c: inline initalize format_context
 7:  b35b287635 =  7:  78e4d75d2b t4205: cover `git log --reflog -z` blindspot
 8:  b0ac175d6f =  8:  9d4dfcc115 pretty: provide short date format
 9:  a4b87ad271 !  9:  5042161d73 pretty: implement 'reference' format
    @@ Documentation/pretty-formats.txt: This is designed to be as compact as possible.
     +
     +	  <abbrev hash> (<title line>, <short author date>)
     ++
    -+This format is useful for referring to other commits when writing a new
    -+commit message. It uses the following canned user format:
    -+`%C(auto)%h (%s, %as)`. This means it will not respect options that
    -+change the output format such as `--date` `--no-abbrev-commit`, and
    -+`--walk-reflogs`.
    ++This format is used to refer to another commit in a commit message and
    ++is the same as `--pretty='format:%C(auto)%h (%s, %as)'`.  As with any
    ++`format:` with format placeholders, its output is not affected by other
    ++options like `--decorate` and `--walk-reflogs`.
     +
      * 'email'
      
    @@ Documentation/rev-list-options.txt: Under `--pretty=oneline`, the commit message
      This option cannot be combined with `--reverse`.
      See also linkgit:git-reflog[1].
     ++
    -+Under `--pretty=summary`, this information will not be shown at all.
    ++Under `--pretty=reference`, this information will not be shown at all.
      
      --merge::
      	After a failed merge, show refs that touch files having a
10:  04d24cbf4b = 10:  888c496991 SubmittingPatches: use `--pretty=reference`
 -:  ---------- > 11:  580aa7c88c squash! pretty: implement 'reference' format
-- 
2.24.0.420.g9ac4901264

[PATCH v4 01/11] SubmittingPatches: use generic terms for hash

[Denton Liu]

Since Git is planning on upgrading from SHA-1 to be more hash-agnostic,
replace specific references to SHA-1 with more generic terminology.

Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
 Documentation/SubmittingPatches | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 1a60cc1329..bb7e33ce15 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -142,7 +142,7 @@ archive, summarize the relevant points of the discussion.
 
 [[commit-reference]]
 If you want to reference a previous commit in the history of a stable
-branch, use the format "abbreviated sha1 (subject, date)",
+branch, use the format "abbreviated hash (subject, date)",
 with the subject enclosed in a pair of double-quotes, like this:
 
 ....
-- 
2.24.0.420.g9ac4901264

[PATCH v4 02/11] pretty-formats.txt: use generic terms for hash

[Denton Liu]

Since Git is planning on upgrading from SHA-1 to be more hash-agnostic,
replace specific references to SHA-1 with more generic terminology.

Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
 Documentation/pretty-formats.txt | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt
index 31c6e8d2b8..4cefa64eeb 100644
--- a/Documentation/pretty-formats.txt
+++ b/Documentation/pretty-formats.txt
@@ -4,7 +4,7 @@ PRETTY FORMATS
 If the commit is a merge, and if the pretty-format
 is not 'oneline', 'email' or 'raw', an additional line is
 inserted before the 'Author:' line.  This line begins with
-"Merge: " and the sha1s of ancestral commits are printed,
+"Merge: " and the hashes of ancestral commits are printed,
 separated by spaces.  Note that the listed commits may not
 necessarily be the list of the *direct* parent commits if you
 have limited your view of history: for example, if you are
@@ -20,20 +20,20 @@ built-in formats:
 
 * 'oneline'
 
-	  <sha1> <title line>
+	  <hash> <title line>
 +
 This is designed to be as compact as possible.
 
 * 'short'
 
-	  commit <sha1>
+	  commit <hash>
 	  Author: <author>
 
 	      <title line>
 
 * 'medium'
 
-	  commit <sha1>
+	  commit <hash>
 	  Author: <author>
 	  Date:   <author date>
 
@@ -43,7 +43,7 @@ This is designed to be as compact as possible.
 
 * 'full'
 
-	  commit <sha1>
+	  commit <hash>
 	  Author: <author>
 	  Commit: <committer>
 
@@ -53,7 +53,7 @@ This is designed to be as compact as possible.
 
 * 'fuller'
 
-	  commit <sha1>
+	  commit <hash>
 	  Author:     <author>
 	  AuthorDate: <author date>
 	  Commit:     <committer>
@@ -65,7 +65,7 @@ This is designed to be as compact as possible.
 
 * 'email'
 
-	  From <sha1> <date>
+	  From <hash> <date>
 	  From: <author>
 	  Date: <author date>
 	  Subject: [PATCH] <title line>
@@ -75,7 +75,7 @@ This is designed to be as compact as possible.
 * 'raw'
 +
 The 'raw' format shows the entire commit exactly as
-stored in the commit object.  Notably, the SHA-1s are
+stored in the commit object.  Notably, the hashes are
 displayed in full, regardless of whether --abbrev or
 --no-abbrev are used, and 'parents' information show the
 true parent commits, without taking grafts or history
-- 
2.24.0.420.g9ac4901264

[PATCH v4 03/11] SubmittingPatches: remove dq from commit reference

[Denton Liu]

Quoting SZEDER Gábor[1],

	SubmittingPatches is simply wrong: our de-facto standard format for
	referencing other commits does not enclose the subject in a pair of
	double-quotes:

	  $ git log v2.24.0 |grep -E '[0-9a-f]{7} \("' |wc -l
	  785
	  $ git log v2.24.0 |grep -E '[0-9a-f]{7} \([^"]' |wc -l
	  2276

	Those double-quotes don't add any value to the references, but they
	result in weird looking references for 1083 of our commits whose
	subject lines happen to end with double-quotes, e.g.:

	  f23a465132 ("hashmap_get{,_from_hash} return "struct hashmap_entry *"", 2019-10-06)

	and without those unnecessary pair of double-quotes we would have
	~3000 more commits whose summary would fit on a single line.

Remove references to the enclosing double-quotes from SubmittingPatches
since our de-facto standard for referencing commits does not actually
use them.

[1]: cf. <20191114011048.GS4348@szeder.dev>

Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
 Documentation/SubmittingPatches | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index bb7e33ce15..7860dd2568 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -142,19 +142,19 @@ archive, summarize the relevant points of the discussion.
 
 [[commit-reference]]
 If you want to reference a previous commit in the history of a stable
-branch, use the format "abbreviated hash (subject, date)",
-with the subject enclosed in a pair of double-quotes, like this:
+branch, use the format "abbreviated hash (subject, date)", like this:
 
 ....
-	Commit f86a374 ("pack-bitmap.c: fix a memleak", 2015-03-30)
+	Commit f86a374 (pack-bitmap.c: fix a memleak, 2015-03-30)
 	noticed that ...
 ....
 
 The "Copy commit summary" command of gitk can be used to obtain this
-format, or this invocation of `git show`:
+format (with the subject enclosed in a pair of double-quotes), or this
+invocation of `git show`:
 
 ....
-	git show -s --date=short --pretty='format:%h ("%s", %ad)' <commit>
+	git show -s --date=short --pretty='format:%h (%s, %ad)' <commit>
 ....
 
 [[git-tools]]
-- 
2.24.0.420.g9ac4901264

[PATCH v4 04/11] completion: complete `tformat:` pretty format

[Denton Liu]

Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
 contrib/completion/git-completion.bash | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/contrib/completion/git-completion.bash b/contrib/completion/git-completion.bash
index 00fbe6c03d..557d0373c3 100644
--- a/contrib/completion/git-completion.bash
+++ b/contrib/completion/git-completion.bash
@@ -1749,7 +1749,7 @@ __git_log_shortlog_options="
 	--all-match --invert-grep
 "
 
-__git_log_pretty_formats="oneline short medium full fuller email raw format: mboxrd"
+__git_log_pretty_formats="oneline short medium full fuller email raw format: tformat: mboxrd"
 __git_log_date_formats="relative iso8601 iso8601-strict rfc2822 short local default raw unix format:"
 
 _git_log ()
-- 
2.24.0.420.g9ac4901264

[PATCH v4 05/11] revision: make get_revision_mark() return const pointer

[Denton Liu]

get_revision_mark() used to return a `char *`, even though all of the
strings it was returning were string literals. Make get_revision_mark()
return a `const char *` so that callers won't be tempted to modify the
returned string.

Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
 revision.c | 4 ++--
 revision.h | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/revision.c b/revision.c
index 0e39b2b8a5..2151b119b7 100644
--- a/revision.c
+++ b/revision.c
@@ -3944,7 +3944,7 @@ struct commit *get_revision(struct rev_info *revs)
 	return c;
 }
 
-char *get_revision_mark(const struct rev_info *revs, const struct commit *commit)
+const char *get_revision_mark(const struct rev_info *revs, const struct commit *commit)
 {
 	if (commit->object.flags & BOUNDARY)
 		return "-";
@@ -3966,7 +3966,7 @@ char *get_revision_mark(const struct rev_info *revs, const struct commit *commit
 
 void put_revision_mark(const struct rev_info *revs, const struct commit *commit)
 {
-	char *mark = get_revision_mark(revs, commit);
+	const char *mark = get_revision_mark(revs, commit);
 	if (!strlen(mark))
 		return;
 	fputs(mark, stdout);
diff --git a/revision.h b/revision.h
index 4134dc6029..addd69410b 100644
--- a/revision.h
+++ b/revision.h
@@ -322,8 +322,8 @@ int handle_revision_arg(const char *arg, struct rev_info *revs,
 void reset_revision_walk(void);
 int prepare_revision_walk(struct rev_info *revs);
 struct commit *get_revision(struct rev_info *revs);
-char *get_revision_mark(const struct rev_info *revs,
-			const struct commit *commit);
+const char *get_revision_mark(const struct rev_info *revs,
+			      const struct commit *commit);
 void put_revision_mark(const struct rev_info *revs,
 		       const struct commit *commit);
 
-- 
2.24.0.420.g9ac4901264

[PATCH v4 06/11] pretty.c: inline initalize format_context

[Denton Liu]

Instead of memsetting and then initializing the fields in the struct,
move the initialization of `format_context` to its assignment.

Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
 pretty.c | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/pretty.c b/pretty.c
index 93eb6e8370..4d633f14fa 100644
--- a/pretty.c
+++ b/pretty.c
@@ -1617,14 +1617,14 @@ void repo_format_commit_message(struct repository *r,
 				const char *format, struct strbuf *sb,
 				const struct pretty_print_context *pretty_ctx)
 {
-	struct format_commit_context context;
+	struct format_commit_context context = {
+		.commit = commit,
+		.pretty_ctx = pretty_ctx,
+		.wrap_start = sb->len
+	};
 	const char *output_enc = pretty_ctx->output_encoding;
 	const char *utf8 = "UTF-8";
 
-	memset(&context, 0, sizeof(context));
-	context.commit = commit;
-	context.pretty_ctx = pretty_ctx;
-	context.wrap_start = sb->len;
 	/*
 	 * convert a commit message to UTF-8 first
 	 * as far as 'format_commit_item' assumes it in UTF-8
-- 
2.24.0.420.g9ac4901264

[PATCH v4 07/11] t4205: cover `git log --reflog -z` blindspot

[Denton Liu]

The test suite does not include any tests where `--reflog` and `-z` are
used together in `git log`. Cover this blindspot. Note that the
`--pretty=oneline` case is written separately because it follows a
slightly different codepath.

Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
 t/t4205-log-pretty-formats.sh | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/t/t4205-log-pretty-formats.sh b/t/t4205-log-pretty-formats.sh
index f42a69faa2..0335b428b1 100755
--- a/t/t4205-log-pretty-formats.sh
+++ b/t/t4205-log-pretty-formats.sh
@@ -134,6 +134,36 @@ test_expect_failure C_LOCALE_OUTPUT 'NUL termination with --stat' '
 	test_cmp expected actual
 '
 
+for p in short medium full fuller email raw
+do
+	test_expect_success "NUL termination with --reflog --pretty=$p" '
+		revs="$(git rev-list --reflog)" &&
+		for r in $revs
+		do
+			git show -s "$r" --pretty="$p" &&
+			printf "\0" || return 1
+		done >expect &&
+		{
+			git log -z --reflog --pretty="$p" &&
+			printf "\0"
+		} >actual &&
+		test_cmp expect actual
+	'
+done
+
+test_expect_success 'NUL termination with --reflog --pretty=oneline' '
+	revs="$(git rev-list --reflog)" &&
+	for r in $revs
+	do
+		git show -s --pretty=oneline "$r" >raw &&
+		cat raw | lf_to_nul || exit 1
+	done >expect &&
+	# the trailing NUL is already produced so we do not need to
+	# output another one
+	git log -z --pretty=oneline --reflog >actual &&
+	test_cmp expect actual
+'
+
 test_expect_success 'setup more commits' '
 	test_commit "message one" one one message-one &&
 	test_commit "message two" two two message-two &&
-- 
2.24.0.420.g9ac4901264

[PATCH v4 08/11] pretty: provide short date format

[Denton Liu]

From: René Scharfe <l.s.r@web.de>

Add the placeholders %as and %cs to format author date and committer
date, respectively, without the time part, like --date=short does, i.e.
like YYYY-MM-DD.

Signed-off-by: René Scharfe <l.s.r@web.de>
Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
 Documentation/pretty-formats.txt | 2 ++
 pretty.c                         | 3 +++
 t/t4205-log-pretty-formats.sh    | 6 ++++++
 3 files changed, 11 insertions(+)

diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt
index 4cefa64eeb..11979301ff 100644
--- a/Documentation/pretty-formats.txt
+++ b/Documentation/pretty-formats.txt
@@ -172,6 +172,7 @@ The placeholders are:
 '%at':: author date, UNIX timestamp
 '%ai':: author date, ISO 8601-like format
 '%aI':: author date, strict ISO 8601 format
+'%as':: author date, short format (`YYYY-MM-DD`)
 '%cn':: committer name
 '%cN':: committer name (respecting .mailmap, see
 	linkgit:git-shortlog[1] or linkgit:git-blame[1])
@@ -187,6 +188,7 @@ The placeholders are:
 '%ct':: committer date, UNIX timestamp
 '%ci':: committer date, ISO 8601-like format
 '%cI':: committer date, strict ISO 8601 format
+'%cs':: committer date, short format (`YYYY-MM-DD`)
 '%d':: ref names, like the --decorate option of linkgit:git-log[1]
 '%D':: ref names without the " (", ")" wrapping.
 '%S':: ref name given on the command line by which the commit was reached
diff --git a/pretty.c b/pretty.c
index 4d633f14fa..4d7f5e9aab 100644
--- a/pretty.c
+++ b/pretty.c
@@ -738,6 +738,9 @@ static size_t format_person_part(struct strbuf *sb, char part,
 	case 'I':	/* date, ISO 8601 strict */
 		strbuf_addstr(sb, show_ident_date(&s, DATE_MODE(ISO8601_STRICT)));
 		return placeholder_len;
+	case 's':
+		strbuf_addstr(sb, show_ident_date(&s, DATE_MODE(SHORT)));
+		return placeholder_len;
 	}
 
 skip:
diff --git a/t/t4205-log-pretty-formats.sh b/t/t4205-log-pretty-formats.sh
index 0335b428b1..da9cacffea 100755
--- a/t/t4205-log-pretty-formats.sh
+++ b/t/t4205-log-pretty-formats.sh
@@ -533,6 +533,12 @@ test_expect_success 'ISO and ISO-strict date formats display the same values' '
 	test_cmp expected actual
 '
 
+test_expect_success 'short date' '
+	git log --format=%ad%n%cd --date=short >expected &&
+	git log --format=%as%n%cs >actual &&
+	test_cmp expected actual
+'
+
 # get new digests (with no abbreviations)
 test_expect_success 'set up log decoration tests' '
 	head1=$(git rev-parse --verify HEAD~0) &&
-- 
2.24.0.420.g9ac4901264

[PATCH v4 09/11] pretty: implement 'reference' format

[Denton Liu]

The standard format for referencing other commits within some projects
(such as git.git) is the reference format. This is described in
Documentation/SubmittingPatches as

	If you want to reference a previous commit in the history of a stable
	branch, use the format "abbreviated hash (subject, date)", like this:

	....
		Commit f86a374 (pack-bitmap.c: fix a memleak, 2015-03-30)
		noticed that ...
	....

Since this format is so commonly used, standardize it as a pretty
format.

The tests that are implemented essentially show that the format-string
does not change in response to various log options. This is useful
because, for future developers, it shows that we've considered the
limitations of the "canned format-string" approach and we are fine with
them.

Based-on-a-patch-by: SZEDER Gábor <szeder.dev@gmail.com>
Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
 Documentation/pretty-formats.txt       |  9 +++++++
 Documentation/pretty-options.txt       |  2 +-
 Documentation/rev-list-options.txt     |  4 ++-
 contrib/completion/git-completion.bash |  2 +-
 pretty.c                               |  4 ++-
 t/t4205-log-pretty-formats.sh          | 36 ++++++++++++++++++++++++++
 6 files changed, 53 insertions(+), 4 deletions(-)

diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt
index 11979301ff..ccd0921123 100644
--- a/Documentation/pretty-formats.txt
+++ b/Documentation/pretty-formats.txt
@@ -63,6 +63,15 @@ This is designed to be as compact as possible.
 
 	       <full commit message>
 
+* 'reference'
+
+	  <abbrev hash> (<title line>, <short author date>)
++
+This format is used to refer to another commit in a commit message and
+is the same as `--pretty='format:%C(auto)%h (%s, %as)'`.  As with any
+`format:` with format placeholders, its output is not affected by other
+options like `--decorate` and `--walk-reflogs`.
+
 * 'email'
 
 	  From <hash> <date>
diff --git a/Documentation/pretty-options.txt b/Documentation/pretty-options.txt
index e44fc8f738..a59426eefd 100644
--- a/Documentation/pretty-options.txt
+++ b/Documentation/pretty-options.txt
@@ -3,7 +3,7 @@
 
 	Pretty-print the contents of the commit logs in a given format,
 	where '<format>' can be one of 'oneline', 'short', 'medium',
-	'full', 'fuller', 'email', 'raw', 'format:<string>'
+	'full', 'fuller', 'reference', 'email', 'raw', 'format:<string>'
 	and 'tformat:<string>'.  When '<format>' is none of the above,
 	and has '%placeholder' in it, it acts as if
 	'--pretty=tformat:<format>' were given.
diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
index 90ff9e2bea..dfa83bddee 100644
--- a/Documentation/rev-list-options.txt
+++ b/Documentation/rev-list-options.txt
@@ -269,7 +269,7 @@ list.
 	exclude (that is, '{caret}commit', 'commit1..commit2',
 	and 'commit1\...commit2' notations cannot be used).
 +
-With `--pretty` format other than `oneline` (for obvious reasons),
+With `--pretty` format other than `oneline` and `reference` (for obvious reasons),
 this causes the output to have two extra lines of information
 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
@@ -293,6 +293,8 @@ 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].
++
+Under `--pretty=reference`, this information will not be shown at all.
 
 --merge::
 	After a failed merge, show refs that touch files having a
diff --git a/contrib/completion/git-completion.bash b/contrib/completion/git-completion.bash
index 557d0373c3..007e6a06d6 100644
--- a/contrib/completion/git-completion.bash
+++ b/contrib/completion/git-completion.bash
@@ -1749,7 +1749,7 @@ __git_log_shortlog_options="
 	--all-match --invert-grep
 "
 
-__git_log_pretty_formats="oneline short medium full fuller email raw format: tformat: mboxrd"
+__git_log_pretty_formats="oneline short medium full fuller reference email raw format: tformat: mboxrd"
 __git_log_date_formats="relative iso8601 iso8601-strict rfc2822 short local default raw unix format:"
 
 _git_log ()
diff --git a/pretty.c b/pretty.c
index 4d7f5e9aab..88a3bc621d 100644
--- a/pretty.c
+++ b/pretty.c
@@ -97,7 +97,9 @@ static void setup_commit_formats(void)
 		{ "mboxrd",	CMIT_FMT_MBOXRD,	0,	0 },
 		{ "fuller",	CMIT_FMT_FULLER,	0,	8 },
 		{ "full",	CMIT_FMT_FULL,		0,	8 },
-		{ "oneline",	CMIT_FMT_ONELINE,	1,	0 }
+		{ "oneline",	CMIT_FMT_ONELINE,	1,	0 },
+		{ "reference",	CMIT_FMT_USERFORMAT,	1,	0,
+			0, "%C(auto)%h (%s, %as)" },
 		/*
 		 * Please update $__git_log_pretty_formats in
 		 * git-completion.bash when you add new formats.
diff --git a/t/t4205-log-pretty-formats.sh b/t/t4205-log-pretty-formats.sh
index da9cacffea..9a9a18f104 100755
--- a/t/t4205-log-pretty-formats.sh
+++ b/t/t4205-log-pretty-formats.sh
@@ -824,4 +824,40 @@ test_expect_success '%S in git log --format works with other placeholders (part
 	test_cmp expect actual
 '
 
+test_expect_success 'log --pretty=reference' '
+	git log --pretty="tformat:%h (%s, %as)" >expect &&
+	git log --pretty=reference >actual &&
+	test_cmp expect actual
+'
+
+test_expect_success 'log --pretty=reference always uses short date' '
+	git log --pretty="tformat:%h (%s, %as)" >expect &&
+	git log --date=rfc --pretty=reference >actual &&
+	test_cmp expect actual
+'
+
+test_expect_success 'log --pretty=reference is never unabbreviated' '
+	git log --pretty="tformat:%h (%s, %as)" >expect &&
+	git log --no-abbrev-commit --pretty=reference >actual &&
+	test_cmp expect actual
+'
+
+test_expect_success 'log --pretty=reference is never decorated' '
+	git log --pretty="tformat:%h (%s, %as)" >expect &&
+	git log --decorate=short --pretty=reference >actual &&
+	test_cmp expect actual
+'
+
+test_expect_success 'log --pretty=reference does not output reflog info' '
+	git log --walk-reflogs --pretty="tformat:%h (%s, %as)" >expect &&
+	git log --walk-reflogs --pretty=reference >actual &&
+	test_cmp expect actual
+'
+
+test_expect_success 'log --pretty=reference is colored appropriately' '
+	git log --color=always --pretty="tformat:%C(auto)%h (%s, %as)" >expect &&
+	git log --color=always --pretty=reference >actual &&
+	test_cmp expect actual
+'
+
 test_done
-- 
2.24.0.420.g9ac4901264

[PATCH v4 10/11] SubmittingPatches: use `--pretty=reference`

[Denton Liu]

Since Git was taught the `--pretty=reference` option, it is no longer
necessary to manually specify the format string to get the commit
reference. Teach users to use the new option while keeping the old
invocation around in case they have an older version of Git.

Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
 Documentation/SubmittingPatches | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 7860dd2568..4515cab519 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -153,6 +153,12 @@ The "Copy commit summary" command of gitk can be used to obtain this
 format (with the subject enclosed in a pair of double-quotes), or this
 invocation of `git show`:
 
+....
+	git show -s --pretty=reference <commit>
+....
+
+or, on an older version of Git without support for --pretty=reference:
+
 ....
 	git show -s --date=short --pretty='format:%h (%s, %ad)' <commit>
 ....
-- 
2.24.0.420.g9ac4901264

[PATCH v4 11/11] squash! pretty: implement 'reference' format

[Denton Liu]

Note that we explicitly special-case `--pretty=reference` to use
`DATE_SHORT` by default in get_commit_format(). Although this isn't a
very elegant way of doing this, it has to be done this way because we
implement `--pretty=reference` as a user-format and, after this
function, it is treated as a normal user-format. This is the only part
of the pretty codepath where we can actually tell that we are dealing
with a "special" format so we have to do it here.

Signed-off-by: Denton Liu <liu.denton@gmail.com>
---

Notes:
    This patch implements the overridable `--date` for `--pretty=reference`.
    The only reason I'm hesitant about squashing this in is, as described
    above, that this patch isn't very elegant. I'd welcome suggestions on
    how to possibly make it more elegant.
    
    Also, if we squash this in, we could drop the "pretty: provide short
    date format" patch. We'd only need to update the test cases to stop
    using `%as`. Thoughts on that?

 Documentation/pretty-formats.txt | 8 +++++---
 pretty.c                         | 8 +++++++-
 t/t4205-log-pretty-formats.sh    | 9 ++++++++-
 3 files changed, 20 insertions(+), 5 deletions(-)

diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt
index ccd0921123..1a7212ce5a 100644
--- a/Documentation/pretty-formats.txt
+++ b/Documentation/pretty-formats.txt
@@ -68,9 +68,11 @@ This is designed to be as compact as possible.
 	  <abbrev hash> (<title line>, <short author date>)
 +
 This format is used to refer to another commit in a commit message and
-is the same as `--pretty='format:%C(auto)%h (%s, %as)'`.  As with any
-`format:` with format placeholders, its output is not affected by other
-options like `--decorate` and `--walk-reflogs`.
+is the same as `--pretty='format:%C(auto)%h (%s, %ad)'`.  By default,
+the date is formatted with `--date=short` unless another `--date` option
+is explicitly specified.  As with any `format:` with format
+placeholders, its output is not affected by other options like
+`--decorate` and `--walk-reflogs`.
 
 * 'email'
 
diff --git a/pretty.c b/pretty.c
index 88a3bc621d..8bb4b1d67f 100644
--- a/pretty.c
+++ b/pretty.c
@@ -99,7 +99,7 @@ static void setup_commit_formats(void)
 		{ "full",	CMIT_FMT_FULL,		0,	8 },
 		{ "oneline",	CMIT_FMT_ONELINE,	1,	0 },
 		{ "reference",	CMIT_FMT_USERFORMAT,	1,	0,
-			0, "%C(auto)%h (%s, %as)" },
+			0, "%C(auto)%h (%s, %ad)" },
 		/*
 		 * Please update $__git_log_pretty_formats in
 		 * git-completion.bash when you add new formats.
@@ -187,6 +187,12 @@ void get_commit_format(const char *arg, struct rev_info *rev)
 		save_user_format(rev, commit_format->user_format,
 				 commit_format->is_tformat);
 	}
+	/*
+	 * --pretty=reference is special; it should use the short date format
+	 * unless otherwise specified
+	 */
+	if (!rev->date_mode_explicit && !strcmp(arg, "reference"))
+		rev->date_mode.type = DATE_SHORT;
 }
 
 /*
diff --git a/t/t4205-log-pretty-formats.sh b/t/t4205-log-pretty-formats.sh
index 9a9a18f104..a8ef3784cf 100755
--- a/t/t4205-log-pretty-formats.sh
+++ b/t/t4205-log-pretty-formats.sh
@@ -830,8 +830,15 @@ test_expect_success 'log --pretty=reference' '
 	test_cmp expect actual
 '
 
-test_expect_success 'log --pretty=reference always uses short date' '
+test_expect_success 'log --pretty=reference with log.date is overridden by short date' '
 	git log --pretty="tformat:%h (%s, %as)" >expect &&
+	test_config log.date rfc &&
+	git log --pretty=reference >actual &&
+	test_cmp expect actual
+'
+
+test_expect_success 'log --pretty=reference with explicit date overrides short date' '
+	git log --date=rfc --pretty="tformat:%h (%s, %ad)" >expect &&
 	git log --date=rfc --pretty=reference >actual &&
 	test_cmp expect actual
 '
-- 
2.24.0.420.g9ac4901264

Re: [PATCH v4 11/11] squash! pretty: implement 'reference' format

[Junio C Hamano]

Denton Liu <liu.denton@gmail.com> writes:

> Note that we explicitly special-case `--pretty=reference` to use
> `DATE_SHORT` by default in get_commit_format(). Although this isn't a
> very elegant way of doing this, it has to be done this way because we
> implement `--pretty=reference` as a user-format and, after this
> function, it is treated as a normal user-format. This is the only part
> of the pretty codepath where we can actually tell that we are dealing
> with a "special" format so we have to do it here.

I was hoping that by extending cmt_fmt_map horizontally, we can
cause the date mode (and other things in the future) to optionally
default to the format specific value, without hardcoding the string
constant in the code.  After all, that (i.e. not having to hardcode
per-format specific constants) is the original point of using
table(s) to describe the customization.

[PATCH v5 00/11] learn the "reference" pretty format

[Denton Liu]

On this mailing list (and many others) the standard way to reference
other commits with the "reference" format, e.g. "f86a374 (pack-bitmap.c:
fix a memleak, 2015-03-30)". Since it's so commonly used, let's
standardise it as a pretty format.

Patches 5-7 were cleanup patches that were critical in earlier
iterations of the series but no longer are critical for the rest of the
patchset. Nonetheless, let's include them since they improve the quality
of the codebase.

Changes since v4:

* Add a column in `struct cmt_fmt_map` to handle the default short date
  of `--pretty=reference`

Changes since v3:

* Change one reference from "summary" to "reference"

* Clarify --pretty=reference documentation

* Add a squashable patch at the end to implement overridable --date

Changes since v2:

* Rename from "summary" to "reference"

* Implement the feature as a canned userformat

* Implement the %*s (short date) format string element

* Remove the enclosing dqs around the subject

Changes since v1:

* Replace more references to "sha1" with "hash"

* Clean up 8/10 by losing the allocation and making the subject less
  misleading

* Add tests in 7/10 to ensure 8/10 does not change any behaviour

Denton Liu (10):
  SubmittingPatches: use generic terms for hash
  pretty-formats.txt: use generic terms for hash
  SubmittingPatches: remove dq from commit reference
  completion: complete `tformat:` pretty format
  revision: make get_revision_mark() return const pointer
  pretty.c: inline initalize format_context
  t4205: cover `git log --reflog -z` blindspot
  pretty: add struct cmt_fmt_map::default_date_mode_type
  pretty: implement 'reference' format
  SubmittingPatches: use `--pretty=reference`

René Scharfe (1):
  pretty: provide short date format

 Documentation/SubmittingPatches        | 16 ++++--
 Documentation/pretty-formats.txt       | 29 +++++++---
 Documentation/pretty-options.txt       |  2 +-
 Documentation/rev-list-options.txt     |  4 +-
 contrib/completion/git-completion.bash |  2 +-
 pretty.c                               | 20 +++++--
 revision.c                             |  4 +-
 revision.h                             |  4 +-
 t/t4205-log-pretty-formats.sh          | 79 ++++++++++++++++++++++++++
 9 files changed, 134 insertions(+), 26 deletions(-)

Range-diff against v4:
 1:  616cda0b4d =  1:  616cda0b4d SubmittingPatches: use generic terms for hash
 2:  badd3d4275 =  2:  badd3d4275 pretty-formats.txt: use generic terms for hash
 3:  ff818446ad =  3:  ff818446ad SubmittingPatches: remove dq from commit reference
 4:  2baa7f8d3d =  4:  2baa7f8d3d completion: complete `tformat:` pretty format
 5:  ac23c4ec45 =  5:  ac23c4ec45 revision: make get_revision_mark() return const pointer
 6:  fa375f8271 =  6:  fa375f8271 pretty.c: inline initalize format_context
 7:  1519677b30 =  7:  1519677b30 t4205: cover `git log --reflog -z` blindspot
 8:  6c41491c3e =  8:  6c41491c3e pretty: provide short date format
 -:  ---------- >  9:  ec05907b62 pretty: add struct cmt_fmt_map::default_date_mode_type
 9:  7b0cf7a39f ! 10:  5264c44fab pretty: implement 'reference' format
    @@ Documentation/pretty-formats.txt: This is designed to be as compact as possible.
     +	  <abbrev hash> (<title line>, <short author date>)
     ++
     +This format is used to refer to another commit in a commit message and
    -+is the same as `--pretty='format:%C(auto)%h (%s, %as)'`.  As with any
    -+`format:` with format placeholders, its output is not affected by other
    -+options like `--decorate` and `--walk-reflogs`.
    ++is the same as `--pretty='format:%C(auto)%h (%s, %ad)'`.  By default,
    ++the date is formatted with `--date=short` unless another `--date` option
    ++is explicitly specified.  As with any `format:` with format
    ++placeholders, its output is not affected by other options like
    ++`--decorate` and `--walk-reflogs`.
     +
      * 'email'
      
    @@ pretty.c: static void setup_commit_formats(void)
     -		{ "oneline",	CMIT_FMT_ONELINE,	1,	0 }
     +		{ "oneline",	CMIT_FMT_ONELINE,	1,	0 },
     +		{ "reference",	CMIT_FMT_USERFORMAT,	1,	0,
    -+			0, "%C(auto)%h (%s, %as)" },
    ++			0, DATE_SHORT, "%C(auto)%h (%s, %ad)" },
      		/*
      		 * Please update $__git_log_pretty_formats in
      		 * git-completion.bash when you add new formats.
    @@ t/t4205-log-pretty-formats.sh: test_expect_success '%S in git log --format works
     +	test_cmp expect actual
     +'
     +
    -+test_expect_success 'log --pretty=reference always uses short date' '
    ++test_expect_success 'log --pretty=reference with log.date is overridden by short date' '
     +	git log --pretty="tformat:%h (%s, %as)" >expect &&
    ++	test_config log.date rfc &&
    ++	git log --pretty=reference >actual &&
    ++	test_cmp expect actual
    ++'
    ++
    ++test_expect_success 'log --pretty=reference with explicit date overrides short date' '
    ++	git log --date=rfc --pretty="tformat:%h (%s, %ad)" >expect &&
     +	git log --date=rfc --pretty=reference >actual &&
     +	test_cmp expect actual
     +'
10:  746481042a = 11:  1281927cb3 SubmittingPatches: use `--pretty=reference`
11:  9d50c069f7 <  -:  ---------- squash! pretty: implement 'reference' format
-- 
2.24.0.420.g9ac4901264

[PATCH v5 01/11] SubmittingPatches: use generic terms for hash

[Denton Liu]

Since Git is planning on upgrading from SHA-1 to be more hash-agnostic,
replace specific references to SHA-1 with more generic terminology.

Signed-off-by: Denton Liu <liu.denton@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/SubmittingPatches | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 6d589e118c..5a00329d5a 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -142,7 +142,7 @@ archive, summarize the relevant points of the discussion.
 
 [[commit-reference]]
 If you want to reference a previous commit in the history of a stable
-branch, use the format "abbreviated sha1 (subject, date)",
+branch, use the format "abbreviated hash (subject, date)",
 with the subject enclosed in a pair of double-quotes, like this:
 
 ....
-- 
2.24.0.420.g9ac4901264

[PATCH v5 02/11] pretty-formats.txt: use generic terms for hash

[Denton Liu]

Since Git is planning on upgrading from SHA-1 to be more hash-agnostic,
replace specific references to SHA-1 with more generic terminology.

Signed-off-by: Denton Liu <liu.denton@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/pretty-formats.txt | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt
index 079598307a..fdccfe5b03 100644
--- a/Documentation/pretty-formats.txt
+++ b/Documentation/pretty-formats.txt
@@ -4,7 +4,7 @@ PRETTY FORMATS
 If the commit is a merge, and if the pretty-format
 is not 'oneline', 'email' or 'raw', an additional line is
 inserted before the 'Author:' line.  This line begins with
-"Merge: " and the sha1s of ancestral commits are printed,
+"Merge: " and the hashes of ancestral commits are printed,
 separated by spaces.  Note that the listed commits may not
 necessarily be the list of the *direct* parent commits if you
 have limited your view of history: for example, if you are
@@ -20,20 +20,20 @@ built-in formats:
 
 * 'oneline'
 
-	  <sha1> <title line>
+	  <hash> <title line>
 +
 This is designed to be as compact as possible.
 
 * 'short'
 
-	  commit <sha1>
+	  commit <hash>
 	  Author: <author>
 
 	      <title line>
 
 * 'medium'
 
-	  commit <sha1>
+	  commit <hash>
 	  Author: <author>
 	  Date:   <author date>
 
@@ -43,7 +43,7 @@ This is designed to be as compact as possible.
 
 * 'full'
 
-	  commit <sha1>
+	  commit <hash>
 	  Author: <author>
 	  Commit: <committer>
 
@@ -53,7 +53,7 @@ This is designed to be as compact as possible.
 
 * 'fuller'
 
-	  commit <sha1>
+	  commit <hash>
 	  Author:     <author>
 	  AuthorDate: <author date>
 	  Commit:     <committer>
@@ -65,7 +65,7 @@ This is designed to be as compact as possible.
 
 * 'email'
 
-	  From <sha1> <date>
+	  From <hash> <date>
 	  From: <author>
 	  Date: <author date>
 	  Subject: [PATCH] <title line>
@@ -75,7 +75,7 @@ This is designed to be as compact as possible.
 * 'raw'
 +
 The 'raw' format shows the entire commit exactly as
-stored in the commit object.  Notably, the SHA-1s are
+stored in the commit object.  Notably, the hashes are
 displayed in full, regardless of whether --abbrev or
 --no-abbrev are used, and 'parents' information show the
 true parent commits, without taking grafts or history
-- 
2.24.0.420.g9ac4901264

[PATCH v5 03/11] SubmittingPatches: remove dq from commit reference

[Denton Liu]

Quoting SZEDER Gábor[1],

	SubmittingPatches is simply wrong: our de-facto standard format for
	referencing other commits does not enclose the subject in a pair of
	double-quotes:

	  $ git log v2.24.0 |grep -E '[0-9a-f]{7} \("' |wc -l
	  785
	  $ git log v2.24.0 |grep -E '[0-9a-f]{7} \([^"]' |wc -l
	  2276

	Those double-quotes don't add any value to the references, but they
	result in weird looking references for 1083 of our commits whose
	subject lines happen to end with double-quotes, e.g.:

	  f23a465132 ("hashmap_get{,_from_hash} return "struct hashmap_entry *"", 2019-10-06)

	and without those unnecessary pair of double-quotes we would have
	~3000 more commits whose summary would fit on a single line.

Remove references to the enclosing double-quotes from SubmittingPatches
since our de-facto standard for referencing commits does not actually
use them.

[1]: cf. <20191114011048.GS4348@szeder.dev>

Signed-off-by: Denton Liu <liu.denton@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/SubmittingPatches | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 5a00329d5a..a1aad13384 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -142,19 +142,19 @@ archive, summarize the relevant points of the discussion.
 
 [[commit-reference]]
 If you want to reference a previous commit in the history of a stable
-branch, use the format "abbreviated hash (subject, date)",
-with the subject enclosed in a pair of double-quotes, like this:
+branch, use the format "abbreviated hash (subject, date)", like this:
 
 ....
-	Commit f86a374 ("pack-bitmap.c: fix a memleak", 2015-03-30)
+	Commit f86a374 (pack-bitmap.c: fix a memleak, 2015-03-30)
 	noticed that ...
 ....
 
 The "Copy commit summary" command of gitk can be used to obtain this
-format, or this invocation of `git show`:
+format (with the subject enclosed in a pair of double-quotes), or this
+invocation of `git show`:
 
 ....
-	git show -s --date=short --pretty='format:%h ("%s", %ad)' <commit>
+	git show -s --date=short --pretty='format:%h (%s, %ad)' <commit>
 ....
 
 [[git-tools]]
-- 
2.24.0.420.g9ac4901264

[PATCH v5 04/11] completion: complete `tformat:` pretty format

[Denton Liu]

Signed-off-by: Denton Liu <liu.denton@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 contrib/completion/git-completion.bash | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/contrib/completion/git-completion.bash b/contrib/completion/git-completion.bash
index e087c4bf00..6bf91ab154 100644
--- a/contrib/completion/git-completion.bash
+++ b/contrib/completion/git-completion.bash
@@ -1737,7 +1737,7 @@ __git_log_shortlog_options="
 	--all-match --invert-grep
 "
 
-__git_log_pretty_formats="oneline short medium full fuller email raw format: mboxrd"
+__git_log_pretty_formats="oneline short medium full fuller email raw format: tformat: mboxrd"
 __git_log_date_formats="relative iso8601 iso8601-strict rfc2822 short local default raw unix format:"
 
 _git_log ()
-- 
2.24.0.420.g9ac4901264

[PATCH v5 05/11] revision: make get_revision_mark() return const pointer

[Denton Liu]

get_revision_mark() used to return a `char *`, even though all of the
strings it was returning were string literals. Make get_revision_mark()
return a `const char *` so that callers won't be tempted to modify the
returned string.

Signed-off-by: Denton Liu <liu.denton@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 revision.c | 4 ++--
 revision.h | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/revision.c b/revision.c
index 07412297f0..2eb9ff089b 100644
--- a/revision.c
+++ b/revision.c
@@ -3934,7 +3934,7 @@ struct commit *get_revision(struct rev_info *revs)
 	return c;
 }
 
-char *get_revision_mark(const struct rev_info *revs, const struct commit *commit)
+const char *get_revision_mark(const struct rev_info *revs, const struct commit *commit)
 {
 	if (commit->object.flags & BOUNDARY)
 		return "-";
@@ -3956,7 +3956,7 @@ char *get_revision_mark(const struct rev_info *revs, const struct commit *commit
 
 void put_revision_mark(const struct rev_info *revs, const struct commit *commit)
 {
-	char *mark = get_revision_mark(revs, commit);
+	const char *mark = get_revision_mark(revs, commit);
 	if (!strlen(mark))
 		return;
 	fputs(mark, stdout);
diff --git a/revision.h b/revision.h
index 4134dc6029..addd69410b 100644
--- a/revision.h
+++ b/revision.h
@@ -322,8 +322,8 @@ int handle_revision_arg(const char *arg, struct rev_info *revs,
 void reset_revision_walk(void);
 int prepare_revision_walk(struct rev_info *revs);
 struct commit *get_revision(struct rev_info *revs);
-char *get_revision_mark(const struct rev_info *revs,
-			const struct commit *commit);
+const char *get_revision_mark(const struct rev_info *revs,
+			      const struct commit *commit);
 void put_revision_mark(const struct rev_info *revs,
 		       const struct commit *commit);
 
-- 
2.24.0.420.g9ac4901264

[PATCH v5 06/11] pretty.c: inline initalize format_context

[Denton Liu]

Instead of memsetting and then initializing the fields in the struct,
move the initialization of `format_context` to its assignment.

Signed-off-by: Denton Liu <liu.denton@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 pretty.c | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/pretty.c b/pretty.c
index e4ed14effe..da154affd4 100644
--- a/pretty.c
+++ b/pretty.c
@@ -1612,14 +1612,14 @@ void repo_format_commit_message(struct repository *r,
 				const char *format, struct strbuf *sb,
 				const struct pretty_print_context *pretty_ctx)
 {
-	struct format_commit_context context;
+	struct format_commit_context context = {
+		.commit = commit,
+		.pretty_ctx = pretty_ctx,
+		.wrap_start = sb->len
+	};
 	const char *output_enc = pretty_ctx->output_encoding;
 	const char *utf8 = "UTF-8";
 
-	memset(&context, 0, sizeof(context));
-	context.commit = commit;
-	context.pretty_ctx = pretty_ctx;
-	context.wrap_start = sb->len;
 	/*
 	 * convert a commit message to UTF-8 first
 	 * as far as 'format_commit_item' assumes it in UTF-8
-- 
2.24.0.420.g9ac4901264

[PATCH v5 07/11] t4205: cover `git log --reflog -z` blindspot

[Denton Liu]

The test suite does not include any tests where `--reflog` and `-z` are
used together in `git log`. Cover this blindspot. Note that the
`--pretty=oneline` case is written separately because it follows a
slightly different codepath.

Signed-off-by: Denton Liu <liu.denton@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 t/t4205-log-pretty-formats.sh | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/t/t4205-log-pretty-formats.sh b/t/t4205-log-pretty-formats.sh
index f42a69faa2..0335b428b1 100755
--- a/t/t4205-log-pretty-formats.sh
+++ b/t/t4205-log-pretty-formats.sh
@@ -134,6 +134,36 @@ test_expect_failure C_LOCALE_OUTPUT 'NUL termination with --stat' '
 	test_cmp expected actual
 '
 
+for p in short medium full fuller email raw
+do
+	test_expect_success "NUL termination with --reflog --pretty=$p" '
+		revs="$(git rev-list --reflog)" &&
+		for r in $revs
+		do
+			git show -s "$r" --pretty="$p" &&
+			printf "\0" || return 1
+		done >expect &&
+		{
+			git log -z --reflog --pretty="$p" &&
+			printf "\0"
+		} >actual &&
+		test_cmp expect actual
+	'
+done
+
+test_expect_success 'NUL termination with --reflog --pretty=oneline' '
+	revs="$(git rev-list --reflog)" &&
+	for r in $revs
+	do
+		git show -s --pretty=oneline "$r" >raw &&
+		cat raw | lf_to_nul || exit 1
+	done >expect &&
+	# the trailing NUL is already produced so we do not need to
+	# output another one
+	git log -z --pretty=oneline --reflog >actual &&
+	test_cmp expect actual
+'
+
 test_expect_success 'setup more commits' '
 	test_commit "message one" one one message-one &&
 	test_commit "message two" two two message-two &&
-- 
2.24.0.420.g9ac4901264

[PATCH v5 08/11] pretty: provide short date format

[Denton Liu]

From: René Scharfe <l.s.r@web.de>

Add the placeholders %as and %cs to format author date and committer
date, respectively, without the time part, like --date=short does, i.e.
like YYYY-MM-DD.

Signed-off-by: René Scharfe <l.s.r@web.de>
Signed-off-by: Denton Liu <liu.denton@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/pretty-formats.txt | 2 ++
 pretty.c                         | 3 +++
 t/t4205-log-pretty-formats.sh    | 6 ++++++
 3 files changed, 11 insertions(+)

diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt
index fdccfe5b03..34bbc39273 100644
--- a/Documentation/pretty-formats.txt
+++ b/Documentation/pretty-formats.txt
@@ -169,6 +169,7 @@ The placeholders are:
 '%at':: author date, UNIX timestamp
 '%ai':: author date, ISO 8601-like format
 '%aI':: author date, strict ISO 8601 format
+'%as':: author date, short format (`YYYY-MM-DD`)
 '%cn':: committer name
 '%cN':: committer name (respecting .mailmap, see
 	linkgit:git-shortlog[1] or linkgit:git-blame[1])
@@ -181,6 +182,7 @@ The placeholders are:
 '%ct':: committer date, UNIX timestamp
 '%ci':: committer date, ISO 8601-like format
 '%cI':: committer date, strict ISO 8601 format
+'%cs':: committer date, short format (`YYYY-MM-DD`)
 '%d':: ref names, like the --decorate option of linkgit:git-log[1]
 '%D':: ref names without the " (", ")" wrapping.
 '%S':: ref name given on the command line by which the commit was reached
diff --git a/pretty.c b/pretty.c
index da154affd4..61014cc25a 100644
--- a/pretty.c
+++ b/pretty.c
@@ -731,6 +731,9 @@ static size_t format_person_part(struct strbuf *sb, char part,
 	case 'I':	/* date, ISO 8601 strict */
 		strbuf_addstr(sb, show_ident_date(&s, DATE_MODE(ISO8601_STRICT)));
 		return placeholder_len;
+	case 's':
+		strbuf_addstr(sb, show_ident_date(&s, DATE_MODE(SHORT)));
+		return placeholder_len;
 	}
 
 skip:
diff --git a/t/t4205-log-pretty-formats.sh b/t/t4205-log-pretty-formats.sh
index 0335b428b1..da9cacffea 100755
--- a/t/t4205-log-pretty-formats.sh
+++ b/t/t4205-log-pretty-formats.sh
@@ -533,6 +533,12 @@ test_expect_success 'ISO and ISO-strict date formats display the same values' '
 	test_cmp expected actual
 '
 
+test_expect_success 'short date' '
+	git log --format=%ad%n%cd --date=short >expected &&
+	git log --format=%as%n%cs >actual &&
+	test_cmp expected actual
+'
+
 # get new digests (with no abbreviations)
 test_expect_success 'set up log decoration tests' '
 	head1=$(git rev-parse --verify HEAD~0) &&
-- 
2.24.0.420.g9ac4901264

[PATCH v5 09/11] pretty: add struct cmt_fmt_map::default_date_mode_type

[Denton Liu]

In a future commit, we plan on having a pretty format which will use a
default date format unless otherwise overidden. Add support for this by
adding a `default_date_mode_type` member in `struct cmt_fmt_map`.

Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
 pretty.c | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/pretty.c b/pretty.c
index 61014cc25a..63fa600276 100644
--- a/pretty.c
+++ b/pretty.c
@@ -20,6 +20,7 @@ static struct cmt_fmt_map {
 	int is_tformat;
 	int expand_tabs_in_log;
 	int is_alias;
+	enum date_mode_type default_date_mode_type;
 	const char *user_format;
 } *commit_formats;
 static size_t builtin_formats_len;
@@ -181,6 +182,8 @@ void get_commit_format(const char *arg, struct rev_info *rev)
 	rev->commit_format = commit_format->format;
 	rev->use_terminator = commit_format->is_tformat;
 	rev->expand_tabs_in_log_default = commit_format->expand_tabs_in_log;
+	if (!rev->date_mode_explicit && commit_format->default_date_mode_type)
+		rev->date_mode.type = commit_format->default_date_mode_type;
 	if (commit_format->format == CMIT_FMT_USERFORMAT) {
 		save_user_format(rev, commit_format->user_format,
 				 commit_format->is_tformat);
-- 
2.24.0.420.g9ac4901264

[PATCH v5 10/11] pretty: implement 'reference' format

[Denton Liu]

The standard format for referencing other commits within some projects
(such as git.git) is the reference format. This is described in
Documentation/SubmittingPatches as

	If you want to reference a previous commit in the history of a stable
	branch, use the format "abbreviated hash (subject, date)", like this:

	....
		Commit f86a374 (pack-bitmap.c: fix a memleak, 2015-03-30)
		noticed that ...
	....

Since this format is so commonly used, standardize it as a pretty
format.

The tests that are implemented essentially show that the format-string
does not change in response to various log options. This is useful
because, for future developers, it shows that we've considered the
limitations of the "canned format-string" approach and we are fine with
them.

Based-on-a-patch-by: SZEDER Gábor <szeder.dev@gmail.com>
Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
 Documentation/pretty-formats.txt       | 11 +++++++
 Documentation/pretty-options.txt       |  2 +-
 Documentation/rev-list-options.txt     |  4 ++-
 contrib/completion/git-completion.bash |  2 +-
 pretty.c                               |  4 ++-
 t/t4205-log-pretty-formats.sh          | 43 ++++++++++++++++++++++++++
 6 files changed, 62 insertions(+), 4 deletions(-)

diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt
index 34bbc39273..0df418e609 100644
--- a/Documentation/pretty-formats.txt
+++ b/Documentation/pretty-formats.txt
@@ -63,6 +63,17 @@ This is designed to be as compact as possible.
 
 	       <full commit message>
 
+* 'reference'
+
+	  <abbrev hash> (<title line>, <short author date>)
++
+This format is used to refer to another commit in a commit message and
+is the same as `--pretty='format:%C(auto)%h (%s, %ad)'`.  By default,
+the date is formatted with `--date=short` unless another `--date` option
+is explicitly specified.  As with any `format:` with format
+placeholders, its output is not affected by other options like
+`--decorate` and `--walk-reflogs`.
+
 * 'email'
 
 	  From <hash> <date>
diff --git a/Documentation/pretty-options.txt b/Documentation/pretty-options.txt
index e44fc8f738..a59426eefd 100644
--- a/Documentation/pretty-options.txt
+++ b/Documentation/pretty-options.txt
@@ -3,7 +3,7 @@
 
 	Pretty-print the contents of the commit logs in a given format,
 	where '<format>' can be one of 'oneline', 'short', 'medium',
-	'full', 'fuller', 'email', 'raw', 'format:<string>'
+	'full', 'fuller', 'reference', 'email', 'raw', 'format:<string>'
 	and 'tformat:<string>'.  When '<format>' is none of the above,
 	and has '%placeholder' in it, it acts as if
 	'--pretty=tformat:<format>' were given.
diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
index bb1251c036..b94ed85c7a 100644
--- a/Documentation/rev-list-options.txt
+++ b/Documentation/rev-list-options.txt
@@ -269,7 +269,7 @@ list.
 	exclude (that is, '{caret}commit', 'commit1..commit2',
 	and 'commit1\...commit2' notations cannot be used).
 +
-With `--pretty` format other than `oneline` (for obvious reasons),
+With `--pretty` format other than `oneline` and `reference` (for obvious reasons),
 this causes the output to have two extra lines of information
 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
@@ -293,6 +293,8 @@ 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].
++
+Under `--pretty=reference`, this information will not be shown at all.
 
 --merge::
 	After a failed merge, show refs that touch files having a
diff --git a/contrib/completion/git-completion.bash b/contrib/completion/git-completion.bash
index 6bf91ab154..889e707a05 100644
--- a/contrib/completion/git-completion.bash
+++ b/contrib/completion/git-completion.bash
@@ -1737,7 +1737,7 @@ __git_log_shortlog_options="
 	--all-match --invert-grep
 "
 
-__git_log_pretty_formats="oneline short medium full fuller email raw format: tformat: mboxrd"
+__git_log_pretty_formats="oneline short medium full fuller reference email raw format: tformat: mboxrd"
 __git_log_date_formats="relative iso8601 iso8601-strict rfc2822 short local default raw unix format:"
 
 _git_log ()
diff --git a/pretty.c b/pretty.c
index 63fa600276..5fc8b730d8 100644
--- a/pretty.c
+++ b/pretty.c
@@ -98,7 +98,9 @@ static void setup_commit_formats(void)
 		{ "mboxrd",	CMIT_FMT_MBOXRD,	0,	0 },
 		{ "fuller",	CMIT_FMT_FULLER,	0,	8 },
 		{ "full",	CMIT_FMT_FULL,		0,	8 },
-		{ "oneline",	CMIT_FMT_ONELINE,	1,	0 }
+		{ "oneline",	CMIT_FMT_ONELINE,	1,	0 },
+		{ "reference",	CMIT_FMT_USERFORMAT,	1,	0,
+			0, DATE_SHORT, "%C(auto)%h (%s, %ad)" },
 		/*
 		 * Please update $__git_log_pretty_formats in
 		 * git-completion.bash when you add new formats.
diff --git a/t/t4205-log-pretty-formats.sh b/t/t4205-log-pretty-formats.sh
index da9cacffea..a8ef3784cf 100755
--- a/t/t4205-log-pretty-formats.sh
+++ b/t/t4205-log-pretty-formats.sh
@@ -824,4 +824,47 @@ test_expect_success '%S in git log --format works with other placeholders (part
 	test_cmp expect actual
 '
 
+test_expect_success 'log --pretty=reference' '
+	git log --pretty="tformat:%h (%s, %as)" >expect &&
+	git log --pretty=reference >actual &&
+	test_cmp expect actual
+'
+
+test_expect_success 'log --pretty=reference with log.date is overridden by short date' '
+	git log --pretty="tformat:%h (%s, %as)" >expect &&
+	test_config log.date rfc &&
+	git log --pretty=reference >actual &&
+	test_cmp expect actual
+'
+
+test_expect_success 'log --pretty=reference with explicit date overrides short date' '
+	git log --date=rfc --pretty="tformat:%h (%s, %ad)" >expect &&
+	git log --date=rfc --pretty=reference >actual &&
+	test_cmp expect actual
+'
+
+test_expect_success 'log --pretty=reference is never unabbreviated' '
+	git log --pretty="tformat:%h (%s, %as)" >expect &&
+	git log --no-abbrev-commit --pretty=reference >actual &&
+	test_cmp expect actual
+'
+
+test_expect_success 'log --pretty=reference is never decorated' '
+	git log --pretty="tformat:%h (%s, %as)" >expect &&
+	git log --decorate=short --pretty=reference >actual &&
+	test_cmp expect actual
+'
+
+test_expect_success 'log --pretty=reference does not output reflog info' '
+	git log --walk-reflogs --pretty="tformat:%h (%s, %as)" >expect &&
+	git log --walk-reflogs --pretty=reference >actual &&
+	test_cmp expect actual
+'
+
+test_expect_success 'log --pretty=reference is colored appropriately' '
+	git log --color=always --pretty="tformat:%C(auto)%h (%s, %as)" >expect &&
+	git log --color=always --pretty=reference >actual &&
+	test_cmp expect actual
+'
+
 test_done
-- 
2.24.0.420.g9ac4901264

[PATCH v5 11/11] SubmittingPatches: use `--pretty=reference`

[Denton Liu]

Since Git was taught the `--pretty=reference` option, it is no longer
necessary to manually specify the format string to get the commit
reference. Teach users to use the new option while keeping the old
invocation around in case they have an older version of Git.

Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
 Documentation/SubmittingPatches | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index a1aad13384..af9fb356ca 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -153,6 +153,12 @@ The "Copy commit summary" command of gitk can be used to obtain this
 format (with the subject enclosed in a pair of double-quotes), or this
 invocation of `git show`:
 
+....
+	git show -s --pretty=reference <commit>
+....
+
+or, on an older version of Git without support for --pretty=reference:
+
 ....
 	git show -s --date=short --pretty='format:%h (%s, %ad)' <commit>
 ....
-- 
2.24.0.420.g9ac4901264

Re: [PATCH v5 09/11] pretty: add struct cmt_fmt_map::default_date_mode_type

[Junio C Hamano]

Denton Liu <liu.denton@gmail.com> writes:

> In a future commit, we plan on having a pretty format which will use a
> default date format unless otherwise overidden. Add support for this by
> adding a `default_date_mode_type` member in `struct cmt_fmt_map`.
>
> Signed-off-by: Denton Liu <liu.denton@gmail.com>
> ---
>  pretty.c | 3 +++
>  1 file changed, 3 insertions(+)

Yup, that is what I meant.  expand_tabs_in_log and friends are
good examples of per-format tweak defined in this table, and the
default date mode is a good addition.

Thanks.

>
> diff --git a/pretty.c b/pretty.c
> index 61014cc25a..63fa600276 100644
> --- a/pretty.c
> +++ b/pretty.c
> @@ -20,6 +20,7 @@ static struct cmt_fmt_map {
>  	int is_tformat;
>  	int expand_tabs_in_log;
>  	int is_alias;
> +	enum date_mode_type default_date_mode_type;
>  	const char *user_format;
>  } *commit_formats;
>  static size_t builtin_formats_len;
> @@ -181,6 +182,8 @@ void get_commit_format(const char *arg, struct rev_info *rev)
>  	rev->commit_format = commit_format->format;
>  	rev->use_terminator = commit_format->is_tformat;
>  	rev->expand_tabs_in_log_default = commit_format->expand_tabs_in_log;
> +	if (!rev->date_mode_explicit && commit_format->default_date_mode_type)
> +		rev->date_mode.type = commit_format->default_date_mode_type;
>  	if (commit_format->format == CMIT_FMT_USERFORMAT) {
>  		save_user_format(rev, commit_format->user_format,
>  				 commit_format->is_tformat);