From: Philip Oakley <philipoakley@iee.email>
Date: Sat, 29 Oct 2022 16:32:47 GMT
Subject: Re: [PATCH v2 2/3] glossary: add "commit graph" description
Message-ID: <d7c818c8-201d-e7d3-f0b9-6d01ab51043c@iee.email>
In-Reply-To: <3a7f43bd-2c48-6a37-7602-f4c938f7f58e@github.com>

On 25/10/2022 13:31, Derrick Stolee wrote:
> On 10/22/2022 6:25 PM, Philip Oakley wrote:
>> Git has an additional "commit graph" capability that supplements the
>> normal commit object's directed acylic graph (DAG). The supplemental
>> commit graph file is designed for speed of access.
>>
>> Describe the commit graph both from the normative DAG view point and
>> from the commit graph file perspective.
> One way to help keep the general term and the file separate is to use
> different notation. "commit graph" (with a space, no formatting) is the
> DAG. "`commit-graph`" (with a dash, code formatting) is the file (and
> its format).
I did want to have separate entries to make clear the distinction at
this level.

The use of the hyphenation is good, and there are only a few places
where that isn't followed, so I'll specifically call out the use of
hyphenation, and add a patch to update the few places that used the
generic term inappropriately.
Using the code formatting for commit-graph would have been extensive.,

>> +[[def_commit_graph_general]]commit graph concept, representations and usage::
>> +	A synonym for the <<def_DAG,DAG>> structure formed by
>> +	the commits in the object database, <<def_ref,referenced>> by branch tips,
>> +	using their <<def_chain,chain>> of linked commits.
>> +	This structure is the definitive commit graph. The
>> +	graph can be represented in other ways, e.g. the
>> +	<<def_commit_graph_file,commit graph file>>.
>> +
>> +[[def_commit_graph_file]]commit graph file::
>> +	The commit-graph file is a supplemental representation of
>> +	the <<def_commit_graph_general,commit graph>> which accelerates
>> +	commit graph walks. The "commit-graph" file is stored
>> +	either in the .git/objects/info directory or in the info directory
>> +	of an alternate object database.
>> +
> So this would become:
>
> [[def_commit_graph_file]]`commit-graph` file::
> 	The `commit-graph` file is a supplemental representation of
> 	the <<def_commit_graph_general,commit graph>> which accelerates
> 	commit graph walks. The `commit-graph` file is stored either in
> 	the `.git/objects/info` directory or in the `info` directory of
> 	an alternate object database.
>
> (I did some extra style and word-wrapping changes, too.)

I've used some of that. Thanks.

Philip
>
> Other than these nits, I find this to be a clear description.
>
> Thanks,
> -Stolee