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

From: kristofferhaugsbakk@fastmail.com <kristofferhaugsbakk@fastmail.com>
Date: May 7, 2026, 19:42 UTC
Message-ID: <V3_caveat_commit-graph.6b6@msgid.xyz>
In-Reply-To: <V2_caveat_commit-graph.68b@msgid.xyz>

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