From 776ba91a5e3349479139e9a51a135d4bc838b613 Mon Sep 17 00:00:00 2001 From: Philip Oakley Date: Sat, 29 Oct 2022 17:41:12 +0100 Subject: [PATCH 1/4] doc: use "commit-graph" hyphenation consistently Note, historical release notes have not been updated. Signed-off-by: Philip Oakley Signed-off-by: Taylor Blau --- Documentation/config/core.txt | 2 +- Documentation/gitformat-commit-graph.txt | 6 +++--- Documentation/technical/commit-graph.txt | 6 +++--- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/Documentation/config/core.txt b/Documentation/config/core.txt index 37afbaf5a4..dfbdaf00b8 100644 --- a/Documentation/config/core.txt +++ b/Documentation/config/core.txt @@ -618,7 +618,7 @@ but risks losing recent work in the event of an unclean system shutdown. * `loose-object` hardens objects added to the repo in loose-object form. * `pack` hardens objects added to the repo in packfile form. * `pack-metadata` hardens packfile bitmaps and indexes. -* `commit-graph` hardens the commit graph file. +* `commit-graph` hardens the commit-graph file. * `index` hardens the index when it is modified. * `objects` is an aggregate option that is equivalent to `loose-object,pack`. diff --git a/Documentation/gitformat-commit-graph.txt b/Documentation/gitformat-commit-graph.txt index 7324665716..31cad585e2 100644 --- a/Documentation/gitformat-commit-graph.txt +++ b/Documentation/gitformat-commit-graph.txt @@ -3,7 +3,7 @@ gitformat-commit-graph(5) NAME ---- -gitformat-commit-graph - Git commit graph format +gitformat-commit-graph - Git commit-graph format SYNOPSIS -------- @@ -14,7 +14,7 @@ $GIT_DIR/objects/info/commit-graphs/* DESCRIPTION ----------- -The Git commit graph stores a list of commit OIDs and some associated +The Git commit-graph stores a list of commit OIDs and some associated metadata, including: - The generation number of the commit. @@ -34,7 +34,7 @@ corresponding to the array position within the list of commit OIDs. Due to some special constants we use to track parents, we can store at most (1 << 30) + (1 << 29) + (1 << 28) - 1 (around 1.8 billion) commits. -== Commit graph files have the following format: +== Commit-graph files have the following format: In order to allow extensions that add extra data to the graph, we organize the body into "chunks" and provide a binary lookup table at the beginning diff --git a/Documentation/technical/commit-graph.txt b/Documentation/technical/commit-graph.txt index 90c9760c23..d821365b18 100644 --- a/Documentation/technical/commit-graph.txt +++ b/Documentation/technical/commit-graph.txt @@ -1,4 +1,4 @@ -Git Commit Graph Design Notes +Git Commit-Graph Design Notes ============================= Git walks the commit graph for many reasons, including: @@ -95,7 +95,7 @@ with default order), but is not used when the topological order is required (such as merge base calculations, "git log --graph"). In practice, we expect some commits to be created recently and not stored -in the commit graph. We can treat these commits as having "infinite" +in the commit-graph. We can treat these commits as having "infinite" generation number and walk until reaching commits with known generation number. @@ -149,7 +149,7 @@ Design Details helpful for these clones, anyway. The commit-graph will not be read or written when shallow commits are present. -Commit Graphs Chains +Commit-Graphs Chains -------------------- Typically, repos grow with near-constant velocity (commits per day). Over time, From fa8e8d5b31f2accfe956e9fd0f67ccb90586ed65 Mon Sep 17 00:00:00 2001 From: Philip Oakley Date: Sat, 29 Oct 2022 17:41:09 +0100 Subject: [PATCH 2/4] doc: use 'object database' not ODB or abbreviation The abbreviation 'ODB' is used in the technical documentation sections for commit-graph and parallel-checkout, along with an 'odb' option in `git-pack-redundant`, without expansion. Use 'object database' in full, in those entries. The text has not been reflowed to keep the changes minimal. While in the glossary for `object` terms, add the common`oid` abbreviation to its entry. Signed-off-by: Philip Oakley Signed-off-by: Taylor Blau --- Documentation/git-pack-redundant.txt | 2 +- Documentation/glossary-content.txt | 2 +- Documentation/technical/commit-graph.txt | 2 +- Documentation/technical/parallel-checkout.txt | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/Documentation/git-pack-redundant.txt b/Documentation/git-pack-redundant.txt index dda80a740c..99ef13839d 100644 --- a/Documentation/git-pack-redundant.txt +++ b/Documentation/git-pack-redundant.txt @@ -34,7 +34,7 @@ OPTIONS --alt-odb:: Don't require objects present in packs from alternate object - directories to be present in local packs. + database (odb) directories to be present in local packs. --verbose:: Outputs some statistics to stderr. Has a small performance penalty. diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt index aa2f41f5e7..947ac49606 100644 --- a/Documentation/glossary-content.txt +++ b/Documentation/glossary-content.txt @@ -262,7 +262,7 @@ This commit is referred to as a "merge commit", or sometimes just a identified by its <>. The objects usually live in `$GIT_DIR/objects/`. -[[def_object_identifier]]object identifier:: +[[def_object_identifier]]object identifier (oid):: Synonym for <>. [[def_object_name]]object name:: diff --git a/Documentation/technical/commit-graph.txt b/Documentation/technical/commit-graph.txt index d821365b18..86fed0de0f 100644 --- a/Documentation/technical/commit-graph.txt +++ b/Documentation/technical/commit-graph.txt @@ -17,7 +17,7 @@ There are two main costs here: The commit-graph file is a supplemental data structure that accelerates commit graph walks. If a user downgrades or disables the 'core.commitGraph' -config setting, then the existing ODB is sufficient. The file is stored +config setting, then the existing object database is sufficient. The file is stored as "commit-graph" either in the .git/objects/info directory or in the info directory of an alternate. diff --git a/Documentation/technical/parallel-checkout.txt b/Documentation/technical/parallel-checkout.txt index e790258a1a..47c9b6183c 100644 --- a/Documentation/technical/parallel-checkout.txt +++ b/Documentation/technical/parallel-checkout.txt @@ -56,7 +56,7 @@ Rejected Multi-Threaded Solution The most "straightforward" implementation would be to spread the set of to-be-updated cache entries across multiple threads. But due to the -thread-unsafe functions in the ODB code, we would have to use locks to +thread-unsafe functions in the object database code, we would have to use locks to coordinate the parallel operation. An early prototype of this solution showed that the multi-threaded checkout would bring performance improvements over the sequential code, but there was still too much lock From 4973726c5dfbaebdab95dab52b4c05b2a637d3fb Mon Sep 17 00:00:00 2001 From: Philip Oakley Date: Sat, 29 Oct 2022 17:41:10 +0100 Subject: [PATCH 3/4] glossary: add "commit graph" description Git has an additional "commit graph" capability that supplements the 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 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. 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 Signed-off-by: Taylor Blau --- Documentation/glossary-content.txt | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt index 947ac49606..a526710278 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 <> 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 <> by a branch <>, which moves forward as additional development is done on the branch. A single Git <> 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 <> and advancing <> to point at the new commit. +[[def_commit_graph_general]]commit graph concept, representations and usage:: + A synonym for the <> structure formed by the commits + in the object database, <> by branch tips, + using their <> 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:: + The "commit-graph" (normally hyphenated) file is a supplemental + representation of the <> + 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 <> which contains the information about a particular <>, such as <>, committer, From 8fea12ab40aab3e0590a5980ce336437b5dcc694 Mon Sep 17 00:00:00 2001 From: Philip Oakley Date: Sat, 29 Oct 2022 17:41:11 +0100 Subject: [PATCH 4/4] glossary: add reachability bitmap description Describe the purpose of the reachability bitmap. Signed-off-by: Philip Oakley Signed-off-by: Taylor Blau --- Documentation/glossary-content.txt | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt index a526710278..5a537268e2 100644 --- a/Documentation/glossary-content.txt +++ b/Documentation/glossary-content.txt @@ -508,6 +508,14 @@ exclude;; <> to the trees or <> that they contain. +[[def_reachability_bitmap]]reachability bitmaps:: + Reachability bitmaps store information about the + <> 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 <> to a different base, and reset the <> of that branch