Subject: Re: [PATCH 2/4] glossary: add commit graph description

From: Junio C Hamano <[email-masked]>
Date: Sat, 09 Jul 2022 14:20:55 -0700

"Philip Oakley via GitGitGadget" <[email-masked]> writes:

> +[[def_commit_graph]]commit graph::
> +	The commit-graph file is a supplemental data structure that
> +	accelerates commit graph walks. The existing Object Data Base (ODB)
> +	is the definitive commit graph. The "commit-graph" file is stored
> +	either in the .git/objects/info directory or in the info directory
> +	of an alternate object database.

While it says nothing technically incorrect, I suspect "The existing
object data base is the definitive commit graph" may invite unneeded
confusion.

I think you wanted to say that the DAG formed by traversing the
pointers recorded in the objects is the authoritative source of
truth and the commit-graph file is merely a precomputed cache and
can be safely lost, but I am not sure the above description conveys
that to anybody who does not already know it.

    The commits in the object data base form a directed acyclic
    graph (DAG) by commits referring to their parent commits.
    Pieces of information from individual commit objects that are
    needed to traverse the DAG are pre-computed in the commit-graph
    file and stored in ...

is my attempt---I am not very happy or proud about it, but it may be
easier to follow.

Thanks.