Re: [PATCH] doc: add caveat about turning off commit-graph

From: Derrick Stolee <stolee@gmail.com>
Date: May 6, 2026, 13:59 UTC
Message-ID: <5f9f4998-4538-4bc1-a245-4248e18c4e86@gmail.com>
In-Reply-To: <caveat_commit-graph.671@msgid.xyz>

On 5/5/2026 4:45 PM, kristofferhaugsbakk@fastmail.com wrote:

Show 14 quoted lines

> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
> 
> The doc `technical/commit-graph.adoc` says that replace objects and
> commit grafts turn off commit-graph:
> 
>     Commit grafts and replace objects can change the shape of the commit
>     history. The latter can also be enabled/disabled on the fly using
>     `--no-replace-objects`. This leads to difficulty storing both possible
>     interpretations of a commit id, especially when computing generation
>     numbers. The commit-graph will not be read or written when
>     replace-objects or grafts are present.
> 
> But this isn’t mentioned in the user-facing doc. Let’s mention it on
> git-replace(1) and git-commit-graph(1).

I like your initiative to present this incompatibility in the user-facing docs.

Show 6 quoted lines

> +CAVEATS
> +-------
> +
> +The existence of replace objects or commit grafts turns off reading or
> +writing to the commit-graph. See linkgit:git-replace[1].
> +

This does seem a little weak. It doesn't really say how this will impact the user. Perhaps we could add something about how performance will likely degrade in this mode?

  The existence of replace objects or commit grafts turns off reading or
  writing to the commit-graph, which can cause performance issues. See
  linkgit:git-replace[1].

Thanks, -Stolee