From bd00717eab1f2c9e9f50d8bca3fa81f7f953f283 Mon Sep 17 00:00:00 2001 From: Denton Liu Date: Tue, 19 Nov 2019 16:51:03 -0800 Subject: SubmittingPatches: use generic terms for hash Since Git is planning on upgrading from SHA-1 to be more hash-agnostic, replace specific references to SHA-1 with more generic terminology. Signed-off-by: Denton Liu Signed-off-by: Junio C Hamano --- Documentation/SubmittingPatches | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/SubmittingPatches') diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 6d589e118c..5a00329d5a 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -142,7 +142,7 @@ archive, summarize the relevant points of the discussion. [[commit-reference]] If you want to reference a previous commit in the history of a stable -branch, use the format "abbreviated sha1 (subject, date)", +branch, use the format "abbreviated hash (subject, date)", with the subject enclosed in a pair of double-quotes, like this: .... -- cgit v1.2.3 From fb2ffa77a6cbd0f4b996befe372f1c7a1b881e66 Mon Sep 17 00:00:00 2001 From: Denton Liu Date: Tue, 19 Nov 2019 16:51:08 -0800 Subject: SubmittingPatches: remove dq from commit reference MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Quoting SZEDER Gábor[1], SubmittingPatches is simply wrong: our de-facto standard format for referencing other commits does not enclose the subject in a pair of double-quotes: $ git log v2.24.0 |grep -E '[0-9a-f]{7} \("' |wc -l 785 $ git log v2.24.0 |grep -E '[0-9a-f]{7} \([^"]' |wc -l 2276 Those double-quotes don't add any value to the references, but they result in weird looking references for 1083 of our commits whose subject lines happen to end with double-quotes, e.g.: f23a465132 ("hashmap_get{,_from_hash} return "struct hashmap_entry *"", 2019-10-06) and without those unnecessary pair of double-quotes we would have ~3000 more commits whose summary would fit on a single line. Remove references to the enclosing double-quotes from SubmittingPatches since our de-facto standard for referencing commits does not actually use them. [1]: cf. <20191114011048.GS4348@szeder.dev> Signed-off-by: Denton Liu Signed-off-by: Junio C Hamano --- Documentation/SubmittingPatches | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'Documentation/SubmittingPatches') diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 5a00329d5a..a1aad13384 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -142,19 +142,19 @@ archive, summarize the relevant points of the discussion. [[commit-reference]] If you want to reference a previous commit in the history of a stable -branch, use the format "abbreviated hash (subject, date)", -with the subject enclosed in a pair of double-quotes, like this: +branch, use the format "abbreviated hash (subject, date)", like this: .... - Commit f86a374 ("pack-bitmap.c: fix a memleak", 2015-03-30) + Commit f86a374 (pack-bitmap.c: fix a memleak, 2015-03-30) noticed that ... .... The "Copy commit summary" command of gitk can be used to obtain this -format, or this invocation of `git show`: +format (with the subject enclosed in a pair of double-quotes), or this +invocation of `git show`: .... - git show -s --date=short --pretty='format:%h ("%s", %ad)' + git show -s --date=short --pretty='format:%h (%s, %ad)' .... [[git-tools]] -- cgit v1.2.3 From 3798149a74f0c2b84b42b108b4fc6ce28c6ab023 Mon Sep 17 00:00:00 2001 From: Denton Liu Date: Tue, 19 Nov 2019 16:51:28 -0800 Subject: SubmittingPatches: use `--pretty=reference` Since Git was taught the `--pretty=reference` option, it is no longer necessary to manually specify the format string to get the commit reference. Teach users to use the new option while keeping the old invocation around in case they have an older version of Git. Signed-off-by: Denton Liu Signed-off-by: Junio C Hamano --- Documentation/SubmittingPatches | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'Documentation/SubmittingPatches') diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index a1aad13384..af9fb356ca 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -153,6 +153,12 @@ The "Copy commit summary" command of gitk can be used to obtain this format (with the subject enclosed in a pair of double-quotes), or this invocation of `git show`: +.... + git show -s --pretty=reference +.... + +or, on an older version of Git without support for --pretty=reference: + .... git show -s --date=short --pretty='format:%h (%s, %ad)' .... -- cgit v1.2.3