On Wed, 12 Aug 2020 at 15:30, Derrick Stolee <stolee@xxxxxxxxx> wrote: > > On 8/7/2020 6:29 PM, Martin Ågren wrote: > > On Thu, 6 Aug 2020 at 18:50, Derrick Stolee via GitGitGadget > > <gitgitgadget@xxxxxxxxx> wrote: > >> 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
