{"thread":{"id":"64563","subject":"[PATCH 4/4] docs: update show-index hash algorithm for breaking changes mode","startedAt":"2025-12-02T01:46:17Z","lastAt":"2025-12-02T11:52:34Z","messageCount":8,"participants":["brian m. carlson","Junio C Hamano","Patrick Steinhardt"],"isPatch":true,"patchVersion":1,"patchTotal":4},"messages":[{"id":"531530","messageId":"20251202014605.52110-5-sandals@crustytoothpaste.net","threadId":"64563","inReplyTo":"20251202014605.52110-1-sandals@crustytoothpaste.net","subject":"[PATCH 4/4] docs: update show-index hash algorithm for breaking changes mode","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2025-12-02T01:46:05Z","receivedAt":"2025-12-02T01:46:17Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"When compiled with WITH_BREAKING_CHANGES, the default hash algorithm\nswitches to SHA-256, but the documentation doesn't reflect this.  Update\nthe show-index manual page to reflect the correct algorithm in this\ncase.\n\nBe sure to conditionalize only full sentences to aid in localization.\n\nSigned-off-by: brian m. carlson <sandals@crustytoothpaste.net>\n---\n Documentation/git-show-index.adoc | 14 +++++++++++---\n 1 file changed, 11 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-show-index.adoc b/Documentation/git-show-index.adoc\nindex 00b3a908cd..af5c114bb8 100644\n--- a/Documentation/git-show-index.adoc\n+++ b/Documentation/git-show-index.adoc\n@@ -41,9 +41,17 @@ OPTIONS\n \n --object-format=<hash-algorithm>::\n \tSpecify the given object format (hash algorithm) for the index file.  The\n-\tvalid values are 'sha1' and (if enabled) 'sha256'.  The default is the\n-\talgorithm for the current repository (set by `extensions.objectFormat`), or\n-\t'sha1' if no value is set or outside a repository..\n+\tvalid values are 'sha1' and (if enabled) 'sha256'.\n+ifndef::with-breaking-changes[]\n+\tThe default is the algorithm for the current repository (set by\n+\t`extensions.objectFormat`), or 'sha1' if no value is set or outside a\n+\trepository.\n+endif::with-breaking-changes[]\n+ifdef::with-breaking-changes[]\n+\tThe default is the algorithm for the current repository (set by\n+\t`extensions.objectFormat`), or 'sha256' if no value is set or outside a\n+\trepository.\n+endif::with-breaking-changes[]\n +\n include::object-format-disclaimer.adoc[]\n \n"},{"id":"531531","messageId":"20251202014605.52110-1-sandals@crustytoothpaste.net","threadId":"64563","inReplyTo":null,"subject":"[PATCH 0/4] Fix doc default hash algorithm in WITH_BREAKING_CHANGES mode","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2025-12-02T01:46:01Z","receivedAt":"2025-12-02T01:46:17Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"When WITH_BREAKING_CHANGES is defined, the default hash algorithm is not\nSHA-1, but SHA-256.  However, our documentation was never updated to\nreflect this, and as a result, we end up misinforming users.\n\nThis series fixes four places where we indicate a default hash algorithm\nin our documentation such that they conditionally say that either SHA-1\nor SHA-256 is the default, based on the the with-breaking-changes\nattribute.  This both improves accuracy now and also makes it less\nlikely that we'll forget to update these places when we hit Git 3.0.\n\nbrian m. carlson (4):\n  docs: update git hash algorithm for breaking changes mode\n  docs: update index-pack hash algorithm for breaking changes mode\n  docs: update init hash algorithm for breaking changes mode\n  docs: update show-index hash algorithm for breaking changes mode\n\n Documentation/git-index-pack.adoc | 14 +++++++++++---\n Documentation/git-init.adoc       |  8 +++++++-\n Documentation/git-show-index.adoc | 14 +++++++++++---\n Documentation/git.adoc            |  8 +++++++-\n 4 files changed, 36 insertions(+), 8 deletions(-)\n\n"},{"id":"531532","messageId":"20251202014605.52110-2-sandals@crustytoothpaste.net","threadId":"64563","inReplyTo":"20251202014605.52110-1-sandals@crustytoothpaste.net","subject":"[PATCH 1/4] docs: update git hash algorithm for breaking changes mode","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2025-12-02T01:46:02Z","receivedAt":"2025-12-02T01:46:17Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"When compiled with WITH_BREAKING_CHANGES, the default hash algorithm\nswitches to SHA-256, but the documentation doesn't reflect this.  Update\nthe main git manual page to reflect the correct algorithm in this case.\n\nBe sure to conditionalize only full sentences to aid in localization.\n\nSigned-off-by: brian m. carlson <sandals@crustytoothpaste.net>\n---\n Documentation/git.adoc | 8 +++++++-\n 1 file changed, 7 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git.adoc b/Documentation/git.adoc\nindex ce099e78b8..6123ebcb1b 100644\n--- a/Documentation/git.adoc\n+++ b/Documentation/git.adoc\n@@ -576,7 +576,13 @@ double-quotes and respecting backslash escapes. E.g., the value\n \tIf this variable is set, the default hash algorithm for new\n \trepositories will be set to this value. This value is\n \tignored when cloning and the setting of the remote repository\n-\tis always used. The default is \"sha1\".\n+\tis always used.\n+ifndef::with-breaking-changes[]\n+\tThe default is \"sha1\".\n+endif::with-breaking-changes[]\n+ifdef::with-breaking-changes[]\n+\tThe default is \"sha256\".\n+endif::with-breaking-changes[]\n \tSee `--object-format` in linkgit:git-init[1].\n \n `GIT_DEFAULT_REF_FORMAT`::\n"},{"id":"531533","messageId":"20251202014605.52110-3-sandals@crustytoothpaste.net","threadId":"64563","inReplyTo":"20251202014605.52110-1-sandals@crustytoothpaste.net","subject":"[PATCH 2/4] docs: update index-pack hash algorithm for breaking changes mode","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2025-12-02T01:46:03Z","receivedAt":"2025-12-02T01:46:17Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"When compiled with WITH_BREAKING_CHANGES, the default hash algorithm\nswitches to SHA-256, but the documentation doesn't reflect this.  Update\nthe index-pack manual page to reflect the correct algorithm in this\ncase.\n\nBe sure to conditionalize only full sentences to aid in localization.\n\nSigned-off-by: brian m. carlson <sandals@crustytoothpaste.net>\n---\n Documentation/git-index-pack.adoc | 14 +++++++++++---\n 1 file changed, 11 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-index-pack.adoc b/Documentation/git-index-pack.adoc\nindex 18036953c0..8f05f5494d 100644\n--- a/Documentation/git-index-pack.adoc\n+++ b/Documentation/git-index-pack.adoc\n@@ -125,9 +125,17 @@ information on the possible values of `<msg-id>` and `<severity>`.\n \n --object-format=<hash-algorithm>::\n \tSpecify the given object format (hash algorithm) for the pack.  The valid\n-\tvalues are 'sha1' and (if enabled) 'sha256'.  The default is the algorithm for\n-\tthe current repository (set by `extensions.objectFormat`), or 'sha1' if no\n-\tvalue is set or outside a repository.\n+\tvalues are 'sha1' and (if enabled) 'sha256'.\n+ifndef::with-breaking-changes[]\n+\tThe default is the algorithm for the current repository (set by\n+\t`extensions.objectFormat`), or 'sha1' if no value is set or outside a\n+\trepository.\n+endif::with-breaking-changes[]\n+ifdef::with-breaking-changes[]\n+\tThe default is the algorithm for the current repository (set by\n+\t`extensions.objectFormat`), or 'sha256' if no value is set or outside a\n+\trepository.\n+endif::with-breaking-changes[]\n +\n This option cannot be used with --stdin.\n +\n"},{"id":"531534","messageId":"20251202014605.52110-4-sandals@crustytoothpaste.net","threadId":"64563","inReplyTo":"20251202014605.52110-1-sandals@crustytoothpaste.net","subject":"[PATCH 3/4] docs: update init hash algorithm for breaking changes mode","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2025-12-02T01:46:04Z","receivedAt":"2025-12-02T01:46:17Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"When compiled with WITH_BREAKING_CHANGES, the default hash algorithm\nswitches to SHA-256, but the documentation doesn't reflect this.  Update\nthe init manual page to reflect the correct algorithm in this case.\n\nBe sure to conditionalize only full sentences to aid in localization.\n\nSigned-off-by: brian m. carlson <sandals@crustytoothpaste.net>\n---\n Documentation/git-init.adoc | 8 +++++++-\n 1 file changed, 7 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-init.adoc b/Documentation/git-init.adoc\nindex bab99b9b47..17dfef4654 100644\n--- a/Documentation/git-init.adoc\n+++ b/Documentation/git-init.adoc\n@@ -53,7 +53,13 @@ current working directory.\n \n `--object-format=<format>`::\n Specify the given object _<format>_ (hash algorithm) for the repository.  The valid\n-values are `sha1` and (if enabled) `sha256`.  `sha1` is the default.\n+values are `sha1` and (if enabled) `sha256`.\n+ifndef::with-breaking-changes[]\n+\t`sha1` is the default.\n+endif::with-breaking-changes[]\n+ifdef::with-breaking-changes[]\n+\t`sha256` is the default.\n+endif::with-breaking-changes[]\n +\n include::object-format-disclaimer.adoc[]\n \n"},{"id":"531537","messageId":"xmqqjyz58ivh.fsf@gitster.g","threadId":"64563","inReplyTo":"20251202014605.52110-2-sandals@crustytoothpaste.net","subject":"Re: [PATCH 1/4] docs: update git hash algorithm for breaking changes mode","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-12-02T07:04:18Z","receivedAt":"2025-12-02T07:04:20Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"brian m. carlson\" <sandals@crustytoothpaste.net> writes:\n\n> +ifndef::with-breaking-changes[]\n> +\tThe default is \"sha1\".\n> +endif::with-breaking-changes[]\n> +ifdef::with-breaking-changes[]\n> +\tThe default is \"sha256\".\n> +endif::with-breaking-changes[]\n>  \tSee `--object-format` in linkgit:git-init[1].\n>  \n>  `GIT_DEFAULT_REF_FORMAT`::\n\nI wonder if we can have a macro definition at a central location, so\nthat we can refer to the text without \"ifdef\" everywhere?\n\nCaution: this illustration of the idea seems to work with AsciiDoc\nbut it was typed in an airline lounge with rum-and-coke in my left\nhand and haven't been tested with Asciidoctor at all.  I do not even\nunderstand why many other [attributes] entries like {asterisk} can\nsuccessfully be grokked by Asciidoctor, but we seem to do -alitdd=<>\nin the Makefile for Asciidoctor, so I mimicked it without fully\nunderstanding what is going on.\n\nBut the patch should be good enough to illustrate the idea.\n\n Documentation/Makefile         | 5 +++++\n Documentation/asciidoc.conf.in | 6 ++++++\n Documentation/git.adoc         | 2 +-\n 3 files changed, 12 insertions(+), 1 deletion(-)\n\ndiff --git c/Documentation/Makefile w/Documentation/Makefile\nindex 04e9e10b27..88b8ed55a2 100644\n--- c/Documentation/Makefile\n+++ w/Documentation/Makefile\n@@ -222,6 +222,11 @@ ASCIIDOC_DOCBOOK = docbook5\n ASCIIDOC_EXTRA += -acompat-mode -atabsize=8\n ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions\n ASCIIDOC_EXTRA += -alitdd='&\\#x2d;&\\#x2d;'\n+ifdef WITH_BREAKING_CHANGES\n+ASCIIDOC_EXTRA += -adefaulthash=sha256\n+else\n+ASCIIDOC_EXTRA += -adefaulthash=sha1\n+endif\n ASCIIDOC_EXTRA += -adocinfo=shared\n ASCIIDOC_DEPS = asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS\n DBLATEX_COMMON =\ndiff --git c/Documentation/asciidoc.conf.in w/Documentation/asciidoc.conf.in\nindex ff9ea0a294..2de6b80197 100644\n--- c/Documentation/asciidoc.conf.in\n+++ w/Documentation/asciidoc.conf.in\n@@ -24,6 +24,12 @@ litdd=&#45;&#45;\n manmanual=Git Manual\n mansource=Git @GIT_VERSION@\n revdate=@GIT_DATE@\n+ifdef::with-breaking-changes[]\n+defaulthash=sha256\n+endif::with-breaking-changes[]\n+ifndef::with-breaking-changes[]\n+defaulthash=sha1\n+endif::with-breaking-changes[]\n \n ifdef::doctype-book[]\n [titles]\ndiff --git c/Documentation/git.adoc w/Documentation/git.adoc\nindex 8c6a3f6042..f21dbba5a1 100644\n--- c/Documentation/git.adoc\n+++ w/Documentation/git.adoc\n@@ -576,7 +576,7 @@ double-quotes and respecting backslash escapes. E.g., the value\n \tIf this variable is set, the default hash algorithm for new\n \trepositories will be set to this value. This value is\n \tignored when cloning and the setting of the remote repository\n-\tis always used. The default is \"sha1\".\n+\tis always used. The default is \"{defaulthash}\".\n \tSee `--object-format` in linkgit:git-init[1].\n \n `GIT_DEFAULT_REF_FORMAT`::\n"},{"id":"531543","messageId":"aS6g0Zjzd5OEd-mb@pks.im","threadId":"64563","inReplyTo":"20251202014605.52110-1-sandals@crustytoothpaste.net","subject":"Re: [PATCH 0/4] Fix doc default hash algorithm in WITH_BREAKING_CHANGES mode","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2025-12-02T08:18:25Z","receivedAt":"2025-12-02T08:18:43Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Tue, Dec 02, 2025 at 01:46:01AM +0000, brian m. carlson wrote:\n> When WITH_BREAKING_CHANGES is defined, the default hash algorithm is not\n> SHA-1, but SHA-256.  However, our documentation was never updated to\n> reflect this, and as a result, we end up misinforming users.\n> \n> This series fixes four places where we indicate a default hash algorithm\n> in our documentation such that they conditionally say that either SHA-1\n> or SHA-256 is the default, based on the the with-breaking-changes\n> attribute.  This both improves accuracy now and also makes it less\n> likely that we'll forget to update these places when we hit Git 3.0.\n\nAll of these look good to me. One alternative would be to introduce an\nattribute that we can then reference in the docs. The below patch shows\nhow to do this with Asciidoc, but of course we'd also have to do this\nfor Asciidoctor.\n\nI don't mind much which approach we use, but wanted to suggest this as\nan alternative.\n\nThanks!\n\nPatrick\n\ndiff --git a/Documentation/asciidoc.conf.in b/Documentation/asciidoc.conf.in\nindex ff9ea0a294..fe1c150ec6 100644\n--- a/Documentation/asciidoc.conf.in\n+++ b/Documentation/asciidoc.conf.in\n@@ -24,6 +24,12 @@ litdd=&#45;&#45;\n manmanual=Git Manual\n mansource=Git @GIT_VERSION@\n revdate=@GIT_DATE@\n+ifndef::with-breaking-changes[]\n+default-hash-algo=sha1\n+endif::with-breaking-changes[]\n+ifdef::with-breaking-changes[]\n+default-hash-algo=sha256\n+endif::with-breaking-changes[]\n \n ifdef::doctype-book[]\n [titles]\ndiff --git a/Documentation/git-index-pack.adoc b/Documentation/git-index-pack.adoc\nindex 18036953c0..730c3835e6 100644\n--- a/Documentation/git-index-pack.adoc\n+++ b/Documentation/git-index-pack.adoc\n@@ -126,7 +126,7 @@ information on the possible values of `<msg-id>` and `<severity>`.\n --object-format=<hash-algorithm>::\n \tSpecify the given object format (hash algorithm) for the pack.  The valid\n \tvalues are 'sha1' and (if enabled) 'sha256'.  The default is the algorithm for\n-\tthe current repository (set by `extensions.objectFormat`), or 'sha1' if no\n+\tthe current repository (set by `extensions.objectFormat`), or '{default-hash-algo}' if no\n \tvalue is set or outside a repository.\n +\n This option cannot be used with --stdin.\n"},{"id":"531552","messageId":"aS7S_zSpfk3r7jxh@fruit.crustytoothpaste.net","threadId":"64563","inReplyTo":"aS6g0Zjzd5OEd-mb@pks.im","subject":"Re: [PATCH 0/4] Fix doc default hash algorithm in WITH_BREAKING_CHANGES mode","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2025-12-02T11:52:31Z","receivedAt":"2025-12-02T11:52:34Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"On 2025-12-02 at 08:18:25, Patrick Steinhardt wrote:\n> On Tue, Dec 02, 2025 at 01:46:01AM +0000, brian m. carlson wrote:\n> > When WITH_BREAKING_CHANGES is defined, the default hash algorithm is not\n> > SHA-1, but SHA-256.  However, our documentation was never updated to\n> > reflect this, and as a result, we end up misinforming users.\n> > \n> > This series fixes four places where we indicate a default hash algorithm\n> > in our documentation such that they conditionally say that either SHA-1\n> > or SHA-256 is the default, based on the the with-breaking-changes\n> > attribute.  This both improves accuracy now and also makes it less\n> > likely that we'll forget to update these places when we hit Git 3.0.\n> \n> All of these look good to me. One alternative would be to introduce an\n> attribute that we can then reference in the docs. The below patch shows\n> how to do this with Asciidoc, but of course we'd also have to do this\n> for Asciidoctor.\n> \n> I don't mind much which approach we use, but wanted to suggest this as\n> an alternative.\n\nI think it may be easier to set this in the Makefile and Meson config,\nbut I'll try to see if I can adopt a similar approach here and if so,\nI'll send a v2.\n-- \nbrian m. carlson (they/them)\nToronto, Ontario, CA\n"}]}