| Message ID | 20221022222539.2333-3-philipoakley@iee.email (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | Add some Glossary of terms information | expand |
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
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
diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt index 947ac49606..97050826e5 100644 --- a/Documentation/glossary-content.txt +++ b/Documentation/glossary-content.txt @@ -20,7 +20,7 @@ [[def_branch]]branch:: A "branch" is a line of development. The most recent <<def_commit,commit>> on a branch is referred to as the tip of - that branch. The tip of the branch is referenced by a branch + that branch. The tip of the branch is <<def_ref,referenced>> by a branch <<def_head,head>>, which moves forward as additional development is done on the branch. A single Git <<def_repository,repository>> can track an arbitrary number of @@ -75,6 +75,21 @@ state in the Git history, by creating a new commit representing the current state of the <<def_index,index>> and advancing <<def_HEAD,HEAD>> to point at the new commit. +[[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. + [[def_commit_object]]commit object:: An <<def_object,object>> which contains the information about a particular <<def_revision,revision>>, such as <<def_parent,parents>>, committer,
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. Also, clarify the link between the branch ref and branch tip by linking to the `ref` glossary entry, matching this commit graph entry. Signed-off-by: Philip Oakley <philipoakley@iee.email> --- Documentation/glossary-content.txt | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-)