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

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

[kristofferhaugsbakk]

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

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
 Documentation/git-commit-graph.adoc | 6 ++++++
 Documentation/git-replace.adoc      | 6 ++++++
 2 files changed, 12 insertions(+)

diff --git a/Documentation/git-commit-graph.adoc b/Documentation/git-commit-graph.adoc
index 6d19026035f..f2a37e91634 100644
--- a/Documentation/git-commit-graph.adoc
+++ b/Documentation/git-commit-graph.adoc
@@ -146,6 +146,12 @@ $ git show-ref -s | git commit-graph write --stdin-commits
 $ git rev-parse HEAD | git commit-graph write --stdin-commits --append
 ------------------------------------------------
 
+CAVEATS
+-------
+
+The existence of replace objects or commit grafts turns off reading or
+writing to the commit-graph. See linkgit:git-replace[1].
+
 CONFIGURATION
 -------------
 
diff --git a/Documentation/git-replace.adoc b/Documentation/git-replace.adoc
index 0a65460adbd..2c0ea07724d 100644
--- a/Documentation/git-replace.adoc
+++ b/Documentation/git-replace.adoc
@@ -145,6 +145,12 @@ commit instead of the replaced commit.
 There may be other problems when using 'git rev-list' related to
 pending objects.
 
+CAVEATS
+-------
+
+The existence of replace objects or commit grafts turns off reading or
+writing to the commit-graph. See linkgit:git-commit-graph[1].
+
 SEE ALSO
 --------
 linkgit:git-hash-object[1]

base-commit: 67ad42147a7acc2af6074753ebd03d904476118f
-- 
2.54.0.13.g9c7419e39f8

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

[Derrick Stolee]

On 5/5/2026 4:45 PM, kristofferhaugsbakk@fastmail.com wrote:
> 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.

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

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

[Kristoffer Haugsbakk]

On Wed, May 6, 2026, at 15:59, Derrick Stolee wrote:
>>[snip]
>>
>> 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.
>
>> +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, that’s good. But I think this addition makes sense only on
git-replace(1). In this (example) git-commit-graph(1) case the whole doc
already explains what the commit-graph is about.

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

[Derrick Stolee]

On 5/7/2026 10:30 AM, Kristoffer Haugsbakk wrote:
> On Wed, May 6, 2026, at 15:59, Derrick Stolee wrote:
>>> [snip]
>>>
>>> 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.
>>
>>> +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, that’s good. But I think this addition makes sense only on
> git-replace(1). In this (example) git-commit-graph(1) case the whole doc
> already explains what the commit-graph is about.

That's fair. Thanks!
-Stolee

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

[kristofferhaugsbakk]

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

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (series):
    v2: Incorporate “performance issues” suggestion on git-replace(1)

 Documentation/git-commit-graph.adoc | 6 ++++++
 Documentation/git-replace.adoc      | 7 +++++++
 2 files changed, 13 insertions(+)

diff --git a/Documentation/git-commit-graph.adoc b/Documentation/git-commit-graph.adoc
index 6d19026035f..f2a37e91634 100644
--- a/Documentation/git-commit-graph.adoc
+++ b/Documentation/git-commit-graph.adoc
@@ -146,6 +146,12 @@ $ git show-ref -s | git commit-graph write --stdin-commits
 $ git rev-parse HEAD | git commit-graph write --stdin-commits --append
 ------------------------------------------------
 
+CAVEATS
+-------
+
+The existence of replace objects or commit grafts turns off reading or
+writing to the commit-graph. See linkgit:git-replace[1].
+
 CONFIGURATION
 -------------
 
diff --git a/Documentation/git-replace.adoc b/Documentation/git-replace.adoc
index 0a65460adbd..436a0e58caf 100644
--- a/Documentation/git-replace.adoc
+++ b/Documentation/git-replace.adoc
@@ -145,6 +145,13 @@ commit instead of the replaced commit.
 There may be other problems when using 'git rev-list' related to
 pending objects.
 
+CAVEATS
+-------
+
+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-commit-graph[1].
+
 SEE ALSO
 --------
 linkgit:git-hash-object[1]

Interdiff against v1:
  diff --git a/Documentation/git-replace.adoc b/Documentation/git-replace.adoc
  index 2c0ea07724d..436a0e58caf 100644
  --- a/Documentation/git-replace.adoc
  +++ b/Documentation/git-replace.adoc
  @@ -149,7 +149,8 @@ CAVEATS
   -------
   
   The existence of replace objects or commit grafts turns off reading or
  -writing to the commit-graph. See linkgit:git-commit-graph[1].
  +writing to the commit-graph, which can cause performance issues. See
  +linkgit:git-commit-graph[1].
   
   SEE ALSO
   --------

base-commit: 67ad42147a7acc2af6074753ebd03d904476118f
-- 
2.54.0.13.g9c7419e39f8

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

[Derrick Stolee]

On 5/7/2026 2:20 PM, kristofferhaugsbakk@fastmail.com wrote:
> 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).
...
> Interdiff against v1:
>   diff --git a/Documentation/git-replace.adoc b/Documentation/git-replace.adoc
>   index 2c0ea07724d..436a0e58caf 100644
>   --- a/Documentation/git-replace.adoc
>   +++ b/Documentation/git-replace.adoc
>   @@ -149,7 +149,8 @@ CAVEATS
>    -------
>    
>    The existence of replace objects or commit grafts turns off reading or
>   -writing to the commit-graph. See linkgit:git-commit-graph[1].
>   +writing to the commit-graph, which can cause performance issues. See
>   +linkgit:git-commit-graph[1].
Thanks for the update! LGTM.

-Stolee

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

[kristofferhaugsbakk]

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

Acked-by: Derrick Stolee <stolee@gmail.com>
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (series):
    v3: Add Ack
    v2: Incorporate “performance issues” suggestion on git-replace(1)

 Documentation/git-commit-graph.adoc | 6 ++++++
 Documentation/git-replace.adoc      | 7 +++++++
 2 files changed, 13 insertions(+)

diff --git a/Documentation/git-commit-graph.adoc b/Documentation/git-commit-graph.adoc
index 6d19026035f..f2a37e91634 100644
--- a/Documentation/git-commit-graph.adoc
+++ b/Documentation/git-commit-graph.adoc
@@ -146,6 +146,12 @@ $ git show-ref -s | git commit-graph write --stdin-commits
 $ git rev-parse HEAD | git commit-graph write --stdin-commits --append
 ------------------------------------------------
 
+CAVEATS
+-------
+
+The existence of replace objects or commit grafts turns off reading or
+writing to the commit-graph. See linkgit:git-replace[1].
+
 CONFIGURATION
 -------------
 
diff --git a/Documentation/git-replace.adoc b/Documentation/git-replace.adoc
index 0a65460adbd..436a0e58caf 100644
--- a/Documentation/git-replace.adoc
+++ b/Documentation/git-replace.adoc
@@ -145,6 +145,13 @@ commit instead of the replaced commit.
 There may be other problems when using 'git rev-list' related to
 pending objects.
 
+CAVEATS
+-------
+
+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-commit-graph[1].
+
 SEE ALSO
 --------
 linkgit:git-hash-object[1]

Interdiff against v2:

Range-diff against v2:
1:  82faa72f7bf ! 1:  fb5ba74ea3e doc: add caveat about turning off commit-graph
    @@ Commit message
         But this isn’t mentioned in the user-facing doc. Let’s mention it on
         git-replace(1) and git-commit-graph(1).
     
    +    Acked-by: Derrick Stolee <stolee@gmail.com>
         Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
      ## Documentation/git-commit-graph.adoc ##

base-commit: 67ad42147a7acc2af6074753ebd03d904476118f
-- 
2.54.0.13.g9c7419e39f8

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

[Derrick Stolee]

On 5/7/2026 3:42 PM, kristofferhaugsbakk@fastmail.com wrote:
> From: Kristoffer Haugsbakk <code@khaugsbakk.name>

> Range-diff against v2:
> 1:  82faa72f7bf ! 1:  fb5ba74ea3e doc: add caveat about turning off commit-graph
>     @@ Commit message
>          But this isn’t mentioned in the user-facing doc. Let’s mention it on
>          git-replace(1) and git-commit-graph(1).
>      
>     +    Acked-by: Derrick Stolee <stolee@gmail.com>
>          Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
>      
>       ## Documentation/git-commit-graph.adoc ##
In general, you don't need to do this. Junio will add these
during his application of the series, if necessary.

Thanks,
-Stolee

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

[Kristoffer Haugsbakk]

On Thu, May 7, 2026, at 21:56, Derrick Stolee wrote:
> On 5/7/2026 3:42 PM, kristofferhaugsbakk@fastmail.com wrote:
>> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
>
>> Range-diff against v2:
>> 1:  82faa72f7bf ! 1:  fb5ba74ea3e doc: add caveat about turning off commit-graph
>>     @@ Commit message
>>          But this isn’t mentioned in the user-facing doc. Let’s mention it on
>>          git-replace(1) and git-commit-graph(1).
>>
>>     +    Acked-by: Derrick Stolee <stolee@gmail.com>
>>          Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
>>
>>       ## Documentation/git-commit-graph.adoc ##
> In general, you don't need to do this. Junio will add these
> during his application of the series, if necessary.

It’s certainly not necessary, yeah. :)

I am basing this on a recollection of someone quoting this from
SubmittingPatches:

    Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:` and
    `Tested-by:` lines as necessary to credit people who helped your
    patch, and "cc:" them when sending such a final version for inclusion.

They said that this was outdated since Junio does it himself. But then
Junio replied and said that it’s good/better if the contributor does it.

I’m terrible at finding back to conversations from more than six months
ago, but it might have been this one:[1]

    >> +Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:` and
    >> +`Tested-by:` lines as necessary to credit people who helped your
    >> +patch, and "cc:" them when sending such a final version for inclusion.
    >
    > Again, not a new problem introduced by this patch, but it seems like
    > all of these are actively wrong. In every case, these trailers are
    > _given_ by reviewers _after_ a series has been submitted (thus, too
    > late for the author to add them), ...

    Well, this is another instance that I may be trying to be too
    helpful and over extending myself, which does not make the process
    scale well (the other one being the "one final resend after the
    list reached a consensus").

    If the authors collect Acks and Reviewed-by's and resend after the
    list reached the concensus, it may take one extra iteration, but I
    no longer have to keep track of these trailers myself, which could
    be a big win.

    So, I dunno.

In conclusion for now: I dunno. :)

† 1: https://lore.kernel.org/git/xmqqo7aiyrxl.fsf@gitster.g/#t

I won’t rush to resubmit over adding a trailer if I know the maintainer
might have already applied the patch. But seeing as how he’s more or
less away-from-inbox right now I figured he won’t beat me to it.

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

[Junio C Hamano]

"Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com> writes:

> On Thu, May 7, 2026, at 21:56, Derrick Stolee wrote:
>> On 5/7/2026 3:42 PM, kristofferhaugsbakk@fastmail.com wrote:
>>> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
>>
>>> Range-diff against v2:
>>> 1:  82faa72f7bf ! 1:  fb5ba74ea3e doc: add caveat about turning off commit-graph
>>>     @@ Commit message
>>>          But this isn’t mentioned in the user-facing doc. Let’s mention it on
>>>          git-replace(1) and git-commit-graph(1).
>>>
>>>     +    Acked-by: Derrick Stolee <stolee@gmail.com>
>>>          Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
>>>
>>>       ## Documentation/git-commit-graph.adoc ##
>> In general, you don't need to do this. Junio will add these
>> during his application of the series, if necessary.
>
> It’s certainly not necessary, yeah. :)
>
> I am basing this on a recollection of someone quoting this from
> SubmittingPatches:
>
>     Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:` and
>     `Tested-by:` lines as necessary to credit people who helped your
>     patch, and "cc:" them when sending such a final version for inclusion.
>
> They said that this was outdated since Junio does it himself. But then
> Junio replied and said that it’s good/better if the contributor does it.

I used to say "let me do this to skip one extra roundtrip" but I
stopped saying so.  Perhaps I should be a bit more explicit and stop
being silently nice to contributors who do not follow the guidelines
to the letter in order to unconfuse you and your friends.  It
actually is a tempting thought.

>     Well, this is another instance that I may be trying to be too
>     helpful and over extending myself, which does not make the process
>     scale well (the other one being the "one final resend after the
>     list reached a consensus").
>
>     If the authors collect Acks and Reviewed-by's and resend after the
>     list reached the concensus, it may take one extra iteration, but I
>     no longer have to keep track of these trailers myself, which could
>     be a big win.
>
>     So, I dunno.
>
> In conclusion for now: I dunno. :)

I do not know either, but if we agree that everybody should do so
themselves and I should refrain from applying the ones that lack
Acks, I can adjust.  There will be lot of unapplied patches left on
the mailing list initially until the contributors adjust their
behaviour, but in the long run it may be beneficial?  

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

[Oswald Buddenhagen]

On Mon, May 11, 2026 at 10:16:56AM +0900, Junio C Hamano wrote:
>There will be lot of unapplied patches left on the mailing list 
>initially until the contributors adjust their behaviour,

>but in the long run it may be beneficial?  
>
no, it won't, because "the contributors" doesn't have a collective mind 
beyond the core group.

every bit of bureaucracy you add just leads to fewer successful (and 
subsequently attempted repeat) contributions.

if the scalability problems with making things contributor-friendly are 
too much for you, then rethink the process/tooling. i've already made my 
case for gerrit [1] ...

[1] https://lore.kernel.org/git/ZcA0NEb+lnjeZUBe@ugly/