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
