learn the "summary" pretty format

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

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

---
 Documentation/pretty-formats.txt | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

index b87e2e83e6..71eef684d0 100644
@@ -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

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.

---
 revision.c | 4 ++--
 revision.h | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

index 0e39b2b8a5..2151b119b7 100644
@@ -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);

index 4134dc6029..addd69410b 100644
@@ -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

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.

---
 builtin/log.c | 2 +-
 revision.c    | 3 ++-
 revision.h    | 2 +-
 3 files changed, 4 insertions(+), 3 deletions(-)

index 89873d2dc2..e4df16be79 100644
@@ -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;
 	}
 

index 2151b119b7..02b49ab754 100644
@@ -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;

index addd69410b..7670f29973 100644
@@ -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

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.

---
 pretty.c | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

index b32f036953..6f2b0ad917 100644
@@ -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

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.

---
 pretty.c | 35 ++++++++++++++++++++++++++++-------
 1 file changed, 28 insertions(+), 7 deletions(-)

index 6f2b0ad917..a6e5fc115a 100644
@@ -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

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().

---
 log-tree.c    | 4 +++-
 reflog-walk.c | 6 +++++-
 2 files changed, 8 insertions(+), 2 deletions(-)

index 923a299e70..4a7d668af6 100644
@@ -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;
+			}
 		}
 	}
 

index 3a25b27d8f..e2b4c0b290 100644
@@ -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

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.

---
 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(-)

index 71eef684d0..5641903b93 100644
@@ -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>

index e44fc8f738..0a5b206193 100644
@@ -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.

index 90ff9e2bea..76df494ed6 100644
@@ -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].

index e4df16be79..ad96a746a3 100644
@@ -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) {

index 4a7d668af6..433adaf0f1 100644
@@ -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);
 			}
 		}
 	}

index a6e5fc115a..8efb2486a5 100644
@@ -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);

index 4ad1fc31ff..6d5b18a4f1 100644
@@ -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,

2.24.0.rc2.262.g2d07a97ef5

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.

---
 Documentation/SubmittingPatches | 6 ++++++
 1 file changed, 6 insertions(+)

index 1a60cc1329..6969ecca45 100644
@@ -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

Hi Eric,

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

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.

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).

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

Hi Junio,

Yep, I'll reword the subject line.

Yep, thats correct.

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

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...

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);
	}

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 <[email protected]>
     
      ## 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 <[email protected]>
     
      ## 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

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

---
 Documentation/SubmittingPatches | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

index 1a60cc1329..bb7e33ce15 100644
@@ -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

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

---
 Documentation/pretty-formats.txt | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

index b87e2e83e6..71eef684d0 100644
@@ -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

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.

---
 revision.c | 4 ++--
 revision.h | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

index 0e39b2b8a5..2151b119b7 100644
@@ -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);

index 4134dc6029..addd69410b 100644
@@ -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

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.

---
 builtin/log.c | 2 +-
 revision.c    | 3 ++-
 revision.h    | 2 +-
 3 files changed, 4 insertions(+), 3 deletions(-)

index 89873d2dc2..e4df16be79 100644
@@ -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;
 	}
 

index 2151b119b7..02b49ab754 100644
@@ -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;

index addd69410b..7670f29973 100644
@@ -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

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.

---
 pretty.c | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

index b32f036953..6f2b0ad917 100644
@@ -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

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.

---
 pretty.c | 35 ++++++++++++++++++++++++++++-------
 1 file changed, 28 insertions(+), 7 deletions(-)

index 6f2b0ad917..a6e5fc115a 100644
@@ -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

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.

---
 t/t4205-log-pretty-formats.sh | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

index f42a69faa2..d35650cae7 100755
@@ -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

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.

---
 log-tree.c    | 4 +++-
 reflog-walk.c | 8 +++++---
 2 files changed, 8 insertions(+), 4 deletions(-)

index 923a299e70..4a7d668af6 100644
@@ -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;
+			}
 		}
 	}
 

index 3a25b27d8f..6b6bd18e6c 100644
@@ -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

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.

---
 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(-)

index 71eef684d0..f9c1296d7c 100644
@@ -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>

index e44fc8f738..0a5b206193 100644
@@ -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.

index 90ff9e2bea..76df494ed6 100644
@@ -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].

index e4df16be79..ad96a746a3 100644
@@ -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) {

index 4a7d668af6..433adaf0f1 100644
@@ -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);
 			}
 		}
 	}

index a6e5fc115a..8efb2486a5 100644
@@ -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);

index 4ad1fc31ff..6d5b18a4f1 100644
@@ -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,

2.24.0.298.g3e88fbd976

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.

---
 Documentation/SubmittingPatches | 6 ++++++
 1 file changed, 6 insertions(+)

index bb7e33ce15..849d27663e 100644
@@ -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

Hi Eric,

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

[...]

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.

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

Make sense. Ignore that suggestion of mine.

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.

Am 08.11.19 um 21:08 schrieb Denton Liu:

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.

---
 Documentation/pretty-formats.txt | 2 ++
 pretty.c                         | 3 +++
 t/t4205-log-pretty-formats.sh    | 6 ++++++
 3 files changed, 11 insertions(+)

index b87e2e83e6..f80eaab439 100644
@@ -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

index b32f036953..76920c91dd 100644
@@ -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:

index f42a69faa2..4980ed4c6f 100755
@@ -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

Am 08.11.19 um 21:08 schrieb Denton Liu:

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é

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.

Hi all,

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?

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

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?).

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.

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 ;-)

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.

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.

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.
-

## 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 <[email protected]>
     
      ## 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 <[email protected]>
         Signed-off-by: Denton Liu <[email protected]>
     
      ## 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 <[email protected]>

## 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.

## 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

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

---
 Documentation/SubmittingPatches | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

index 1a60cc1329..bb7e33ce15 100644
@@ -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

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

---
 Documentation/pretty-formats.txt | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

index 31c6e8d2b8..4cefa64eeb 100644
@@ -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

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. <[email protected]>

---
 Documentation/SubmittingPatches | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

index bb7e33ce15..7860dd2568 100644
@@ -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

---
 contrib/completion/git-completion.bash | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

index 00fbe6c03d..557d0373c3 100644
@@ -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

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.

---
 revision.c | 4 ++--
 revision.h | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

index 0e39b2b8a5..2151b119b7 100644
@@ -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);

index 4134dc6029..addd69410b 100644
@@ -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

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

---
 pretty.c | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

index 93eb6e8370..4d633f14fa 100644
@@ -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

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.

---
 t/t4205-log-pretty-formats.sh | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

index f42a69faa2..0335b428b1 100755
@@ -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

From: René Scharfe <[email protected]>

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.

---
 Documentation/pretty-formats.txt | 2 ++
 pretty.c                         | 3 +++
 t/t4205-log-pretty-formats.sh    | 6 ++++++
 3 files changed, 11 insertions(+)

index 4cefa64eeb..11979301ff 100644
@@ -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

index 4d633f14fa..4d7f5e9aab 100644
@@ -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:

index 0335b428b1..da9cacffea 100755
@@ -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

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.

---
 Documentation/SubmittingPatches | 6 ++++++
 1 file changed, 6 insertions(+)

index 7860dd2568..4515cab519 100644
@@ -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

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.

---
 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(-)

index 11979301ff..ee1a945bae 100644
@@ -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>

index e44fc8f738..a59426eefd 100644
@@ -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.

index 90ff9e2bea..91edeaf6d5 100644
@@ -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

index 557d0373c3..007e6a06d6 100644
@@ -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 ()

index 4d7f5e9aab..88a3bc621d 100644
@@ -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.

index da9cacffea..9a9a18f104 100755
@@ -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

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.

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.

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.

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

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

---
 Documentation/SubmittingPatches | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

index 1a60cc1329..bb7e33ce15 100644
@@ -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

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

---
 Documentation/pretty-formats.txt | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

index 31c6e8d2b8..4cefa64eeb 100644
@@ -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

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. <[email protected]>

---
 Documentation/SubmittingPatches | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

index bb7e33ce15..7860dd2568 100644
@@ -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

---
 contrib/completion/git-completion.bash | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

index 00fbe6c03d..557d0373c3 100644
@@ -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

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.

---
 revision.c | 4 ++--
 revision.h | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

index 0e39b2b8a5..2151b119b7 100644
@@ -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);

index 4134dc6029..addd69410b 100644
@@ -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

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

---
 pretty.c | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

index 93eb6e8370..4d633f14fa 100644
@@ -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

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.

---
 t/t4205-log-pretty-formats.sh | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

index f42a69faa2..0335b428b1 100755
@@ -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

From: René Scharfe <[email protected]>

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.

---
 Documentation/pretty-formats.txt | 2 ++
 pretty.c                         | 3 +++
 t/t4205-log-pretty-formats.sh    | 6 ++++++
 3 files changed, 11 insertions(+)

index 4cefa64eeb..11979301ff 100644
@@ -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

index 4d633f14fa..4d7f5e9aab 100644
@@ -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:

index 0335b428b1..da9cacffea 100755
@@ -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

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.

---
 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(-)

index 11979301ff..ccd0921123 100644
@@ -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>

index e44fc8f738..a59426eefd 100644
@@ -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.

index 90ff9e2bea..dfa83bddee 100644
@@ -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

index 557d0373c3..007e6a06d6 100644
@@ -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 ()

index 4d7f5e9aab..88a3bc621d 100644
@@ -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.

index da9cacffea..9a9a18f104 100755
@@ -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

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.

---
 Documentation/SubmittingPatches | 6 ++++++
 1 file changed, 6 insertions(+)

index 7860dd2568..4515cab519 100644
@@ -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

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.

---

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(-)

index ccd0921123..1a7212ce5a 100644
@@ -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'
 

index 88a3bc621d..8bb4b1d67f 100644
@@ -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;
 }
 
 /*

index 9a9a18f104..a8ef3784cf 100755
@@ -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

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.

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

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

---
 Documentation/SubmittingPatches | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

index 6d589e118c..5a00329d5a 100644
@@ -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

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

---
 Documentation/pretty-formats.txt | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

index 079598307a..fdccfe5b03 100644
@@ -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

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. <[email protected]>

---
 Documentation/SubmittingPatches | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

index 5a00329d5a..a1aad13384 100644
@@ -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

---
 contrib/completion/git-completion.bash | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

index e087c4bf00..6bf91ab154 100644
@@ -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

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.

---
 revision.c | 4 ++--
 revision.h | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

index 07412297f0..2eb9ff089b 100644
@@ -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);

index 4134dc6029..addd69410b 100644
@@ -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

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

---
 pretty.c | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

index e4ed14effe..da154affd4 100644
@@ -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

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.

---
 t/t4205-log-pretty-formats.sh | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

index f42a69faa2..0335b428b1 100755
@@ -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

From: René Scharfe <[email protected]>

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.

---
 Documentation/pretty-formats.txt | 2 ++
 pretty.c                         | 3 +++
 t/t4205-log-pretty-formats.sh    | 6 ++++++
 3 files changed, 11 insertions(+)

index fdccfe5b03..34bbc39273 100644
@@ -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

index da154affd4..61014cc25a 100644
@@ -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:

index 0335b428b1..da9cacffea 100755
@@ -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

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.

---
 pretty.c | 3 +++
 1 file changed, 3 insertions(+)

index 61014cc25a..63fa600276 100644
@@ -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

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.

---
 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(-)

index 34bbc39273..0df418e609 100644
@@ -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>

index e44fc8f738..a59426eefd 100644
@@ -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.

index bb1251c036..b94ed85c7a 100644
@@ -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

index 6bf91ab154..889e707a05 100644
@@ -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 ()

index 63fa600276..5fc8b730d8 100644
@@ -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.

2.24.0.420.g9ac4901264

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.

---
 Documentation/SubmittingPatches | 6 ++++++
 1 file changed, 6 insertions(+)

index a1aad13384..af9fb356ca 100644
@@ -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

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.