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

From: Philip Oakley <philipoakley@iee.email>
Date: Jul 10, 2022, 21:37 UTC
Message-ID: <5551bd33-cf95-3201-0a00-23e02ef41de3@iee.email>
In-Reply-To: <xmqqedyut22w.fsf@gitster.g>

Hi Junio,

On 09/07/2022 22:20, Junio C Hamano wrote:

Show 11 quoted lines

> "Philip Oakley via GitGitGadget" <gitgitgadget@gmail.com> 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 probably over-shortened the original text I was summarising (technical/commit-graph.txt intro).

>
> 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

.. of that graph. *nod*

>  and
> can be safely lost,

I wasn't particularly thinking of that aspect .. Perhaps more that it accelerates commit graph walks..

Show 11 quoted lines

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

I wanted to keepseparate from the graph file definition, the rather fuzzy relationship between the overall ODB (staging area, and loads of other stuff), and the way the DAG is generated, which also needs the selected refs to start the traverse..

In a wider context, it's not clear to me just how the commit graph file content is chosen relative to the full depth DAG from all local refs. The reachability bit maps have a similar info gap.

-- Philip

[sorry for erratic responses - currently isolating with covid]