From: Derrick Stolee <derrickstolee@github.com>
Date: Tue, 25 Oct 2022 12:31:58 GMT
Subject: Re: [PATCH v2 2/3] glossary: add "commit graph" description
Message-ID: <3a7f43bd-2c48-6a37-7602-f4c938f7f58e@github.com>
In-Reply-To: <20221022222539.2333-3-philipoakley@iee.email>

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

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

Other than these nits, I find this to be a clear description.

Thanks,
-Stolee