Re: [PATCH 0/4] Fix doc default hash algorithm in WITH_BREAKING_CHANGES mode

[Patrick Steinhardt <ps@pks.im>]

On Tue, Dec 02, 2025 at 01:46:01AM +0000, brian m. carlson wrote:
> When WITH_BREAKING_CHANGES is defined, the default hash algorithm is not
> SHA-1, but SHA-256.  However, our documentation was never updated to
> reflect this, and as a result, we end up misinforming users.
> 
> This series fixes four places where we indicate a default hash algorithm
> in our documentation such that they conditionally say that either SHA-1
> or SHA-256 is the default, based on the the with-breaking-changes
> attribute.  This both improves accuracy now and also makes it less
> likely that we'll forget to update these places when we hit Git 3.0.

All of these look good to me. One alternative would be to introduce an
attribute that we can then reference in the docs. The below patch shows
how to do this with Asciidoc, but of course we'd also have to do this
for Asciidoctor.

I don't mind much which approach we use, but wanted to suggest this as
an alternative.

Thanks!

Patrick

diff --git a/Documentation/asciidoc.conf.in b/Documentation/asciidoc.conf.in
index ff9ea0a294..fe1c150ec6 100644
--- a/Documentation/asciidoc.conf.in
+++ b/Documentation/asciidoc.conf.in
@@ -24,6 +24,12 @@ litdd=--
 manmanual=Git Manual
 mansource=Git @GIT_VERSION@
 revdate=@GIT_DATE@
+ifndef::with-breaking-changes[]
+default-hash-algo=sha1
+endif::with-breaking-changes[]
+ifdef::with-breaking-changes[]
+default-hash-algo=sha256
+endif::with-breaking-changes[]
 
 ifdef::doctype-book[]
 [titles]
diff --git a/Documentation/git-index-pack.adoc b/Documentation/git-index-pack.adoc
index 18036953c0..730c3835e6 100644
--- a/Documentation/git-index-pack.adoc
+++ b/Documentation/git-index-pack.adoc
@@ -126,7 +126,7 @@ information on the possible values of `<msg-id>` and `<severity>`.
 --object-format=<hash-algorithm>::
 	Specify the given object format (hash algorithm) for the pack.  The valid
 	values are 'sha1' and (if enabled) 'sha256'.  The default is the algorithm for
-	the current repository (set by `extensions.objectFormat`), or 'sha1' if no
+	the current repository (set by `extensions.objectFormat`), or '{default-hash-algo}' if no
 	value is set or outside a repository.
 +
 This option cannot be used with --stdin.