Re: [PATCH 3/8] commit-graph: update design document

[Jakub Narebski <jnareb@gmail.com>]

"Derrick Stolee via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Derrick Stolee <dstolee@microsoft.com>
>
> 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@microsoft.com>
> ---
>  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