doc: add caveat about turning off commit-graph
PATCH 1/1 doc: add caveat about turning off commit-graph
From: Kristoffer Haugsbakk <[email protected]>
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).
--- Documentation/git-commit-graph.adoc | 6 ++++++ Documentation/git-replace.adoc | 6 ++++++ 2 files changed, 12 insertions(+)
Documentation/git-commit-graph.adoc +6 -0
@@ -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 -------------
Documentation/git-replace.adoc +6 -0
@@ -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
Signature · 1 line
2.54.0.13.g9c7419e39f8
Quoted 12 lines · On 5/5/2026 4:45 PM, [email protected] wrote:
From: Kristoffer Haugsbakk <[email protected]>
The doc
technical/commit-graph.adocsays 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.
Quoted 2 lines
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.
Documentation/git-commit-graph.adoc $ git show-ref -s | git commit-graph write --stdin-commits · line 154
Quoted 6 lines
Documentation/git-commit-graph.adoc +6
-0+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
Quoted 18 lines · Derrick Stolee
Quoted 4 lines
[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.
Documentation/git-commit-graph.adoc $ git show-ref -s | git commit-graph write --stdin-commits · line 154
Quoted 6 lines
Documentation/git-commit-graph.adoc +6
-0+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?
Quoted 3 lines
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.
Quoted 19 lines · Kristoffer Haugsbakk
Quoted 18 lines · Derrick Stolee
Quoted 4 lines
[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.
Documentation/git-commit-graph.adoc $ git show-ref -s | git commit-graph write --stdin-commits · line 154
Quoted 6 lines
Documentation/git-commit-graph.adoc +6
-0+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?
Quoted 7 lines
Quoted 3 lines
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 1/1 doc: add caveat about turning off commit-graph
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
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).
---
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(+)
Documentation/git-commit-graph.adoc +6 -0
@@ -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 -------------
Documentation/git-replace.adoc +7 -0
@@ -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
Signature · 1 line
2.54.0.13.g9c7419e39f8
Quoted 14 lines · On 5/7/2026 2:20 PM, [email protected] wrote:
From: Kristoffer Haugsbakk <[email protected]>
The doc
technical/commit-graph.adocsays 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).
...
Quoted 8 lines
Interdiff against v1:
diff --git a/Documentation/git-replace.adoc b/Documentation/git-replace.adoc index2c0ea07724d..436a0e58caf100644
--- a/Documentation/git-replace.adoc
+++ b/Documentation/git-replace.adoc
@@ -149,7 +149,8 @@ CAVEATS
-------
Quoted 4 lines
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 1/1 doc: add caveat about turning off commit-graph
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
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).
---
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(+)
Documentation/git-commit-graph.adoc +6 -0
@@ -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 -------------
Documentation/git-replace.adoc +7 -0
@@ -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 <[email protected]>
## Documentation/git-commit-graph.adoc ##
base-commit: 67ad42147a7acc2af6074753ebd03d904476118f
Signature · 1 line
2.54.0.13.g9c7419e39f8
Quoted 8 lines · On 5/7/2026 3:42 PM, [email protected] wrote:
From: Kristoffer Haugsbakk <[email protected]>
Range-diff against v2:
1:82faa72f7bf! 1:fb5ba74ea3edoc: 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).
Quoted 4 lines
+ Acked-by: Derrick Stolee <[email protected]>
Signed-off-by Kristoffer Haugsbakk <[email protected]>##
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
Quoted 9 lines · Derrick Stolee
Quoted 8 lines · On 5/7/2026 3:42 PM, [email protected] wrote:
From: Kristoffer Haugsbakk <[email protected]>
Range-diff against v2:
1:82faa72f7bf! 1:fb5ba74ea3edoc: 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).
Quoted 6 lines
Quoted 4 lines
+ Acked-by: Derrick Stolee <[email protected]>
Signed-off-by Kristoffer Haugsbakk <[email protected]>##
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]
Quoted 8 lines
Review
Quoted 3 lines
(quoted diff) +3
-0+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/[email protected]/#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.
Quoted 22 lines · Kristoffer Haugsbakk
Quoted 9 lines · Derrick Stolee
Quoted 8 lines · On 5/7/2026 3:42 PM, [email protected] wrote:
From: Kristoffer Haugsbakk <[email protected]>
Range-diff against v2:
1:82faa72f7bf! 1:fb5ba74ea3edoc: 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).Quoted 6 lines
Quoted 4 lines
+ Acked-by: Derrick Stolee <[email protected]>
Signed-off-by Kristoffer Haugsbakk <[email protected]>##
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:
Quoted 6 lines
Do not forget to add trailers such as
Acked-by:,Reviewed-by:andTested-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.
Quoted 5 lines
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").
Quoted 8 lines
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?
Quoted 4 lines · Junio C Hamano
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] ...
Quoted 11 lines · Junio C Hamano
Quoted 11 lines
Quoted 1 line
[snip]
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:andTested-by:lines as necessary to credit people who helped your patch, and "cc:" them when sending such a final version for inclusion.
Quoted 8 lines
Quoted 2 lines
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.
I am personally okay with adding these trailers and think it’s nice to document such review/ack/etc. interactions.
Just considering this part in isolation, I imagine that you not filling in missing acks etc. will lead to less such trailers because (1) most contributors don’t seem to follow up with such updates if the only change is the trailers section, and (2) most people here (culturally) don’t add explicit trailer lines in their replies (e.g. an “LGTM” is clearly an ack, but not explicit).
Quoted 19 lines
Quoted 19 lines
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
Quoted 1 line · Junio C Hamano
[snip]
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:andTested-by:lines as necessary to credit people who helped your patch, and "cc:" them when sending such a final version for inclusion.
Quoted 8 lines
Quoted 2 lines
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.
I am personally okay with adding these trailers and think it’s nice to document such review/ack/etc. interactions.
Just considering this part in isolation, I imagine that you not filling in missing acks etc. will lead to less such trailers because (1) most contributors don’t seem to follow up with such updates if the only change is the trailers section, and (2) most people here (culturally) don’t add explicit trailer lines in their replies (e.g. an “LGTM” is clearly an ack, but not explicit).
Quoted 12 lines
Quoted 12 lines
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.
Quoted 7 lines
Quoted 1 line
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?
Okay, if the proposal is to *not* e.g. graduate series to next that haven’t applied the acks etc. then I understand how it will likely lead to some stalls until people adjust.
To be clear, I imagine this is how it would play out:
• The series in itself is ready for next and has no unapplied acks etc.: it graduates to next
• The series in itself is ready for next but has unapplied acks etc.:
it does not graduate to next since the contributor should send a new version with the trailer changes
***
There is also the paragraph previous to the trailer one:
After the list reached a consensus that it is a good idea to apply the patch, re-send it with "To:" set to the maintainer{current-maintainer} and "cc:" the list{git-ml} for inclusion. This is especially relevant when the maintainer did not heavily participate in the discussion and instead left the review to trusted others.
Do not forget to add trailers such as Acked-by:, [...]
And I have only managed to follow that part maybe, probably one single time.
Quoted 11 lines
Quoted 5 lines
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?
Okay, if the proposal is to *not* e.g. graduate series to next that haven’t applied the acks etc. then I understand how it will likely lead to some stalls until people adjust.
To be clear, I imagine this is how it would play out:
• The series in itself is ready for next and has no unapplied acks etc.: it graduates to next
• The series in itself is ready for next but has unapplied acks etc.:
it does not graduate to next since the contributor should send a new version with the trailer changes
***
There is also the paragraph previous to the trailer one:
After the list reached a consensus that it is a good idea to apply the patch, re-send it with "To:" set to the maintainer{current-maintainer} and "cc:" the list{git-ml} for inclusion. This is especially relevant when the maintainer did not heavily participate in the discussion and instead left the review to trusted others.
Do not forget to add trailers such as Acked-by:, [...]
And I have only managed to follow that part maybe, probably one single time.