From patchwork Sat Oct 29 16:41:09 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Philip Oakley X-Patchwork-Id: 13024721 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 3D932C38A02 for ; Sat, 29 Oct 2022 16:41:30 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229741AbiJ2Ql2 (ORCPT ); Sat, 29 Oct 2022 12:41:28 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:47042 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229682AbiJ2QlZ (ORCPT ); Sat, 29 Oct 2022 12:41:25 -0400 Received: from smtp-out-6.talktalk.net (smtp-out-6.talktalk.net [62.24.135.70]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id BEBAE18358 for ; Sat, 29 Oct 2022 09:41:23 -0700 (PDT) Received: from localhost.localdomain ([88.110.102.84]) by smtp.talktalk.net with SMTP id ootdodzgpnO7EootdoWf28; Sat, 29 Oct 2022 17:41:21 +0100 X-Originating-IP: [88.110.102.84] X-Spam: 0 X-OAuthority: v=2.3 cv=X8gs11be c=1 sm=1 tr=0 a=f4UhoLCnUTRb1HgAgoWw0g==:117 a=f4UhoLCnUTRb1HgAgoWw0g==:17 a=MKtGQD3n3ToA:10 a=1oJP67jkp3AA:10 a=ldyaYNNxDcoA:10 a=vfaYcDn82YOBLiSa2CoA:9 From: Philip Oakley To: GitList Cc: Self , Junio C Hamano , Derrick Stolee , Abhradeep Chakraborty , Taylor Blau Subject: [PATCH v3 1/4] doc: use 'object database' not ODB or abbreviation Date: Sat, 29 Oct 2022 17:41:09 +0100 Message-Id: <20221029164112.2097-2-philipoakley@iee.email> X-Mailer: git-send-email 2.38.1.windows.1 In-Reply-To: <20221029164112.2097-1-philipoakley@iee.email> References: <20221022222539.2333-1-philipoakley@iee.email> <20221029164112.2097-1-philipoakley@iee.email> MIME-Version: 1.0 X-CMAE-Envelope: MS4wfD9Bj+hYmfFgCiNETA+RHPkhKWnVrxfk+s9D8dcUh0IOf++2HDpdsH0eaPQIa2Ktmc9B/xGBBhPd5P99DTutT/CIAYkFJQKA9+9kypQWU8kZiMoXVoWK aBDYbFssfYsbPBHGkvv1sUTmk1gE/Cez50m2Z/iAva1SKMEfJk1Kj6zPe0lfZlNKp48z649bB2b5elnxAHRAAqq9fsX+DrdXji9/qfs0gcRSJv/zXtmD5dSU oXMrbUJ2NMC0HvUv3b3+Gg+xjvOp1/tW5OkrbxfWWHmxLpayXsOOrjmswSxgMrXnXX32WBX+bB2zCbzEw6JOO3oqZ9lsIfPtAPbGdazzytaQLQj85DKmn1Qe dPJg/iBQ Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org 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 --- 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 ee7034b5e5..1132c73956 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 90c9760c23..d2a6a13650 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 patchwork Sat Oct 29 16:41:10 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Philip Oakley X-Patchwork-Id: 13024720 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 4ED13C433FE for ; Sat, 29 Oct 2022 16:41:30 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229720AbiJ2Ql0 (ORCPT ); Sat, 29 Oct 2022 12:41:26 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:47044 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229642AbiJ2QlZ (ORCPT ); Sat, 29 Oct 2022 12:41:25 -0400 Received: from smtp-out-6.talktalk.net (smtp-out-6.talktalk.net [62.24.135.70]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id C6A5A58B47 for ; Sat, 29 Oct 2022 09:41:23 -0700 (PDT) Received: from localhost.localdomain ([88.110.102.84]) by smtp.talktalk.net with SMTP id ootdodzgpnO7EooteoWf2E; Sat, 29 Oct 2022 17:41:22 +0100 X-Originating-IP: [88.110.102.84] X-Spam: 0 X-OAuthority: v=2.3 cv=X8gs11be c=1 sm=1 tr=0 a=f4UhoLCnUTRb1HgAgoWw0g==:117 a=f4UhoLCnUTRb1HgAgoWw0g==:17 a=MKtGQD3n3ToA:10 a=1oJP67jkp3AA:10 a=ldyaYNNxDcoA:10 a=L21Qlja0vAKRWb0B7dUA:9 From: Philip Oakley To: GitList Cc: Self , Junio C Hamano , Derrick Stolee , Abhradeep Chakraborty , Taylor Blau Subject: [PATCH v3 2/4] glossary: add "commit graph" description Date: Sat, 29 Oct 2022 17:41:10 +0100 Message-Id: <20221029164112.2097-3-philipoakley@iee.email> X-Mailer: git-send-email 2.38.1.windows.1 In-Reply-To: <20221029164112.2097-1-philipoakley@iee.email> References: <20221022222539.2333-1-philipoakley@iee.email> <20221029164112.2097-1-philipoakley@iee.email> MIME-Version: 1.0 X-CMAE-Envelope: MS4wfOKsCis3vDScwXOoU+93/5lVtlzNd3Dj8x6CzIUracups1vICUZRpsjtuwrIR1EK0mMVZuRy7Kv6idXopNzlr7ZO56RuNsyCvXphLtdanRddg32GaiUM cmF7PGytbO1myt8ofqqmM+iHG2b43QWL9zdvslSQ7n8zeKx1N+3wF6XVP93Da6sJZIUBHJoSCpvQ+l5KF7vWK/y5YuSvs0uUCOkmQcyx0zJTDMq08GEph58I yJQD4QtQbQBZ1RTaS7m5RqJH5x6LFJLG6hRu75rmN699TxaACh4u3e95Dm4eSAF4PFy+6iovh6iYrhiMrdlXYM2Y1B5+p/D2Bk93O1Zw2RW9qT7sT8Q+BANX 5lXQYKv5 Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org 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 --- 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 patchwork Sat Oct 29 16:41:11 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Philip Oakley X-Patchwork-Id: 13024722 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 7E8D8C433FE for ; Sat, 29 Oct 2022 16:42:01 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229782AbiJ2Ql3 (ORCPT ); Sat, 29 Oct 2022 12:41:29 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:47050 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229616AbiJ2QlZ (ORCPT ); Sat, 29 Oct 2022 12:41:25 -0400 Received: from smtp-out-6.talktalk.net (smtp-out-6.talktalk.net [62.24.135.70]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 04C1F1A81B for ; Sat, 29 Oct 2022 09:41:23 -0700 (PDT) Received: from localhost.localdomain ([88.110.102.84]) by smtp.talktalk.net with SMTP id ootdodzgpnO7EooteoWf2K; Sat, 29 Oct 2022 17:41:22 +0100 X-Originating-IP: [88.110.102.84] X-Spam: 0 X-OAuthority: v=2.3 cv=X8gs11be c=1 sm=1 tr=0 a=f4UhoLCnUTRb1HgAgoWw0g==:117 a=f4UhoLCnUTRb1HgAgoWw0g==:17 a=MKtGQD3n3ToA:10 a=1oJP67jkp3AA:10 a=ldyaYNNxDcoA:10 a=l4iZrl2lBOJF5wAcl3YA:9 From: Philip Oakley To: GitList Cc: Self , Junio C Hamano , Derrick Stolee , Abhradeep Chakraborty , Taylor Blau Subject: [PATCH v3 3/4] glossary: add reachability bitmap description Date: Sat, 29 Oct 2022 17:41:11 +0100 Message-Id: <20221029164112.2097-4-philipoakley@iee.email> X-Mailer: git-send-email 2.38.1.windows.1 In-Reply-To: <20221029164112.2097-1-philipoakley@iee.email> References: <20221022222539.2333-1-philipoakley@iee.email> <20221029164112.2097-1-philipoakley@iee.email> MIME-Version: 1.0 X-CMAE-Envelope: MS4wfOKsCis3vDScwXOoU+93/5lVtlzNd3Dj8x6CzIUracups1vICUZRpsjtuwrIR1EK0mMVZuRy7Kv6idXopNzlr7ZO56RuNsyCvXphLtdanRddg32GaiUM cmF7PGytbO1myt8ofqqmM+iHG2b43QWL9zdvslSQ7n8zeKx1N+3wF6XVP93Da6sJZIUBHJoSCpvQ+l5KF7vWK/y5YuSvs0uUCOkmQcyx0zJTDMq08GEph58I yJQD4QtQbQBZ1RTaS7m5RqJH5x6LFJLG6hRu75rmN699TxaACh4u3e95Dm4eSAF4PFy+6iovh6iYrhiMrdlXYM2Y1B5+p/D2Bk93O1Zw2RW9qT7sT8Q+BANX 5lXQYKv5 Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org Describe the purpose of the reachability bitmap. Signed-off-by: Philip Oakley --- 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 From patchwork Sat Oct 29 16:41:12 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Philip Oakley X-Patchwork-Id: 13024724 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id ADA70FA3744 for ; Sat, 29 Oct 2022 16:42:01 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229838AbiJ2Qlb (ORCPT ); Sat, 29 Oct 2022 12:41:31 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:47048 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229556AbiJ2QlZ (ORCPT ); Sat, 29 Oct 2022 12:41:25 -0400 Received: from smtp-out-6.talktalk.net (smtp-out-6.talktalk.net [62.24.135.70]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 6065E58B4B for ; Sat, 29 Oct 2022 09:41:24 -0700 (PDT) Received: from localhost.localdomain ([88.110.102.84]) by smtp.talktalk.net with SMTP id ootdodzgpnO7EooteoWf2Q; Sat, 29 Oct 2022 17:41:22 +0100 X-Originating-IP: [88.110.102.84] X-Spam: 0 X-OAuthority: v=2.3 cv=X8gs11be c=1 sm=1 tr=0 a=f4UhoLCnUTRb1HgAgoWw0g==:117 a=f4UhoLCnUTRb1HgAgoWw0g==:17 a=MKtGQD3n3ToA:10 a=1oJP67jkp3AA:10 a=ldyaYNNxDcoA:10 a=zw-UjYAx6vlCfjrV0-gA:9 From: Philip Oakley To: GitList Cc: Self , Junio C Hamano , Derrick Stolee , Abhradeep Chakraborty , Taylor Blau Subject: [PATCH v3 4/4] doc: use "commit-graph" hyphenation consistently Date: Sat, 29 Oct 2022 17:41:12 +0100 Message-Id: <20221029164112.2097-5-philipoakley@iee.email> X-Mailer: git-send-email 2.38.1.windows.1 In-Reply-To: <20221029164112.2097-1-philipoakley@iee.email> References: <20221022222539.2333-1-philipoakley@iee.email> <20221029164112.2097-1-philipoakley@iee.email> MIME-Version: 1.0 X-CMAE-Envelope: MS4wfOKsCis3vDScwXOoU+93/5lVtlzNd3Dj8x6CzIUracups1vICUZRpsjtuwrIR1EK0mMVZuRy7Kv6idXopNzlr7ZO56RuNsyCvXphLtdanRddg32GaiUM cmF7PGytbO1myt8ofqqmM+iHG2b43QWL9zdvslSQ7n8zeKx1N+3wF6XVP93Da6sJZIUBHJoSCpvQ+l5KF7vWK/y5YuSvs0uUCOkmQcyx0zJTDMq08GEph58I yJQD4QtQbQBZ1RTaS7m5RqJH5x6LFJLG6hRu75rmN699TxaACh4u3e95Dm4eSAF4PFy+6iovh6iYrhiMrdlXYM2Y1B5+p/D2Bk93O1Zw2RW9qT7sT8Q+BANX 5lXQYKv5 Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org Note, historical release notes have not been updated. Signed-off-by: Philip Oakley # Conflicts: # Documentation/gitformat-commit-graph.txt --- 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 d2a6a13650..86fed0de0f 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,