"Derrick Stolee via GitGitGadget" <gitgitgadget@xxxxxxxxx> writes: > From: Derrick Stolee <dstolee@xxxxxxxxxxxxx> > > As it exists right now, the commit-graph feature may provide > inconsistent results when combined with commit grafts, replace objects, > and shallow clones. Update the design document to discuss why these > interactions are difficult to reconcile and how we will avoid errors by > preventing updates to and reads from the commit-graph file when these > other features exist. > > Signed-off-by: Derrick Stolee <dstolee@xxxxxxxxxxxxx> > --- > Documentation/technical/commit-graph.txt | 18 +++++++++++++++--- > 1 file changed, 15 insertions(+), 3 deletions(-) It would be nice to have this information not only in the technical documentation, but also in user-facing documentation, for example git-commit-graph manpage. > > diff --git a/Documentation/technical/commit-graph.txt b/Documentation/technical/commit-graph.txt > index c664acbd7..18948f11a 100644 > --- a/Documentation/technical/commit-graph.txt > +++ b/Documentation/technical/commit-graph.txt > @@ -112,12 +112,24 @@ Design Details > - The file format includes parameters for the object ID hash function, > so a future change of hash algorithm does not require a change in format. > > +- Commit grafts and replace objects can change the shape of the commit > + history. These can also be enabled/disabled on the fly using I think you meant "The latter can..." instead of "These can...", as grafts cannot be disabled with `--no-replace-objects` option. > + `--no-replace-objects`. This leads to difficultly 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. > + > +- Shallow clones create grafts of commits by dropping their parents. This > + leads the commit-graph to think those commits have generation number 1. > + If and when those commits are made unshallow, those generation numbers > + become invalid. Since shallow clones are intended to restrict the commit > + history to a very small set of commits, the commit-graph feature is less > + helpful for these clones, anyway. The commit-graph will not be read or > + written when shallow commits are present. > + > Future Work > ----------- > > -- The commit graph feature currently does not honor commit grafts. This can > - be remedied by duplicating or refactoring the current graft logic. > - > - After computing and storing generation numbers, we must make graph > walks aware of generation numbers to gain the performance benefits they > enable. This will mostly be accomplished by swapping a commit-date-ordered
