On Wed, 12 Aug 2020 at 15:30, Derrick Stolee [off-list ref] wrote:

On 8/7/2020 6:29 PM, Martin Ågren wrote:

quoted

On Thu, 6 Aug 2020 at 18:50, Derrick Stolee via GitGitGadget
[off-list ref] wrote:

quoted

diff --git a/Documentation/git-maintenance.txt b/Documentation/git-maintenance.txt
index 089fa4cedc..35b0be7d40 100644
--- a/Documentation/git-maintenance.txt
+++ b/Documentation/git-maintenance.txt

@@ -35,6 +35,24 @@ run::
 TASKS
 -----

+commit-graph::
+       The `commit-graph` job updates the `commit-graph` files incrementally,
+       then verifies that the written data is correct. If the new layer has an
+       issue, then the chain file is removed and the `commit-graph` is
+       rewritten from scratch.
++
+The verification only checks the top layer of the `commit-graph` chain.
+If the incremental write merged the new commits with at least one
+existing layer, then there is potential for on-disk corruption being
+carried forward into the new file. This will be noticed and the new
+commit-graph file will be clean as Git reparses the commit data from
+the object database.

This reads somewhat awkwardly. I think what you mean is something like
"is there a risk for on-disk corruption? yes, but no: we're clever
enough to detect it and avoid it". So from a user's point of view, I
think this is too detailed.

[snip quite a bit]

Back to the point of your comments: I'm not sure this second paragraph
is required at all in the documentation. The first paragraph already
says:

        ...then verifies that the written data is correct.

This "written data" _is_ the top layer of the chain. There is probably
no reason to dig deeper into _why_ we do this in this user-facing
documentation.

So, I propose just deleting this paragraph. What do you think?

Yeah, that makes lots of sense. Thanks!


Martin