(in reply to <20221022222539.2333-1-philipoakley@iee.email> This short series looks to add the basics of the reachability bitmap and commit graph phrases to the glossary of terms. While these techniques are well known to their developers, for some, they are just magic phrases. [V3] .. since V2 1/4 Unchanged. 2/4 The distinction between the generic 'commit graph' of the DAG and the implementation specifics of 'commit-graph' file has been retained for the glossary. However the deliberate hyphenation has been included, and a fourth patch added to maintain the consistency of 'commit-graph' in other documents. 3/4 Tweaks & links applied to Reachability patch. 4/4 New - maintain the consistency of 'commit-graph' in other documents. [V2] .. since V1 was GitGitGadget #1282, (in reply to <pull.1282.git.1657385781.gitgitgadget@xxxxxxxxx>) Patch 4/4 has been taken upstream independently, and hence dropped here so we're now just [n/3]. Patch 1/3 Dropped the glossary addition in favour of changing the locations that used ODB (Junio's suggestion). Kept the git pack-redundant's `--alt-odb` but spelt out 'object database' in full in the man page. The only remaining `odb`s are within `goodbye` ;-). While here, add the (oid) abbreviation to its adjacent entry. Patch 2/3 Split the 'commit-graph' explanation into two parts to distinguish the speed-up option, from Git's core graph concept of object traversal. Included links to existing terms. Patch 3/3 Added links to existing terms. Statement for the reachability bitmaps. added cc: for Stolee (commit-graph) and Abhradeep Chakraborty (Bitmaps) review. [V1] [GGG PR #1282] https://lore.kernel.org/git/pull.1282.git.1657385781.gitgitgadget@xxxxxxxxx/ The first patch [1/4] is to show OBD as an abbreviation to avoid a UNA [0] Patch [2/4] provides a basic statement for the Commit-Graph's purpose. Patch [3/4] provides a similar statement for the reachability bitmaps. These two patches maybe misses out on some linking information as to the benefits these have and the basics of their heuristic. Patch [4/4] follows up on a bug report about the lack of idempotence for the `--renormalise' command. See commit message for details. [0] UNA Un-Named Abbreviation. Signed-off-by: Philip Oakley philipoakley@iee.email cc: Philip Oakley philipoakley@iee.email Philip Oakley (4): doc: use 'object database' not ODB or abbreviation glossary: add "commit graph" description glossary: add reachability bitmap description doc: use "commit-graph" hyphenation consistently Documentation/config/core.txt | 2 +- Documentation/git-pack-redundant.txt | 2 +- Documentation/gitformat-commit-graph.txt | 6 ++--- Documentation/glossary-content.txt | 27 +++++++++++++++++-- Documentation/technical/commit-graph.txt | 8 +++--- Documentation/technical/parallel-checkout.txt | 2 +- 6 files changed, 35 insertions(+), 12 deletions(-) Range-diff against remotes/gitster/po/glossary-around-traversal (v2?): 1: de164ab78b ! 1: 748b15345e doc: use 'object database' not ODB or abbreviation @@ Commit message abbreviation to its entry. Signed-off-by: Philip Oakley <philipoakley@iee.email> - Signed-off-by: Junio C Hamano <gitster@xxxxxxxxx> ## Documentation/git-pack-redundant.txt ## @@ Documentation/git-pack-redundant.txt: OPTIONS 2: f677d57699 ! 2: 052a9568e7 glossary: add "commit graph" description @@ Commit message glossary: add "commit graph" description Git has an additional "commit graph" capability that supplements the - normal commit object's directed acylic graph (DAG). The supplemental + normal commit object's directed acyclic 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 @@ Commit message by linking to the `ref` glossary entry, matching this commit graph entry. + The commit-graph file is also distinguished by its hyphenation. + + Subsequent commit catches the few cases where the hyphenation of + commit-graph was missing. + Signed-off-by: Philip Oakley <philipoakley@iee.email> - Signed-off-by: Junio C Hamano <gitster@xxxxxxxxx> ## Documentation/glossary-content.txt ## @@ @@ Documentation/glossary-content.txt: state in the Git history, by creating a new 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, ++ 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>>. + -+[[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_graph_file]]commit-graph file:: ++ The "commit-graph" (normally hyphenated) 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 3: 39e9a282fc ! 3: d56234b70c glossary: add reachability bitmap description @@ Commit message Describe the purpose of the reachability bitmap. Signed-off-by: Philip Oakley <philipoakley@iee.email> - Signed-off-by: Junio C Hamano <gitster@xxxxxxxxx> ## Documentation/glossary-content.txt ## @@ Documentation/glossary-content.txt: exclude;; @@ Documentation/glossary-content.txt: exclude;; +[[def_reachability_bitmap]]reachability bitmaps:: + Reachability bitmaps store information about the -+ <<def_reachable,reachability>> of a selected set of objects in -+ a packfile, or a multi-pack index (MIDX) to speed up object search. -+ A repository may have at -+ most one bitmap. The bitmap may belong to either one pack, or the -+ repository's multi-pack index (if it exists). ++ <<def_reachable,reachability>> of a selected set of commits in ++ a packfile, or a multi-pack index (MIDX), to speed up object search. ++ The bitmaps are stored in a ".bitmap" file. A repository may have at ++ most one bitmap file in use. The bitmap file may belong to either one ++ pack, or the repository's multi-pack index (if it exists). + [[def_rebase]]rebase:: To reapply a series of changes from a <<def_branch,branch>> to a -: ---------- > 4: 87686e63f9 doc: use "commit-graph" hyphenation consistently -- 2.38.1.windows.1
