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

From: Junio C Hamano <gitster@pobox.com>
Date: Jul 9, 2022, 21:20 UTC
Message-ID: <xmqqedyut22w.fsf@gitster.g>
In-Reply-To: <32777cae24de91b0fb873ea04a802630ab85aafe.1657385781.git.gitgitgadget@gmail.com>

"Philip Oakley via GitGitGadget" <gitgitgadget@gmail.com> writes:

Show 6 quoted lines

> +[[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.