From a3a3ca002d0942696eaa41625da8746f55fc7abe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Martin=20=C3=85gren?= Date: Thu, 27 Sep 2018 21:12:19 +0200 Subject: [PATCH 1/4] git-commit-graph.txt: fix bullet lists MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit We have a couple of bullet items which span multiple lines, and where we have prefixed each line with a `*`. (This might be the result of a text editor trying to help.) This results in each line being typeset as a separate bullet item. Drop the extra `*`. Signed-off-by: Martin Ågren Reviewed-by: Derrick Stolee Signed-off-by: Junio C Hamano --- Documentation/git-commit-graph.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/git-commit-graph.txt b/Documentation/git-commit-graph.txt index dececb79d7..f42f2a1481 100644 --- a/Documentation/git-commit-graph.txt +++ b/Documentation/git-commit-graph.txt @@ -73,7 +73,7 @@ $ git commit-graph write ------------------------------------------------ * Write a graph file, extending the current graph file using commits -* in . + in . + ------------------------------------------------ $ echo | git commit-graph write --stdin-packs @@ -86,7 +86,7 @@ $ git show-ref -s | git commit-graph write --stdin-commits ------------------------------------------------ * Write a graph file containing all commits in the current -* commit-graph file along with those reachable from HEAD. + commit-graph file along with those reachable from HEAD. + ------------------------------------------------ $ git rev-parse HEAD | git commit-graph write --stdin-commits --append From d59a9168fb65b02d20eda3100a76670417087c96 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Martin=20=C3=85gren?= Date: Thu, 27 Sep 2018 21:12:20 +0200 Subject: [PATCH 2/4] git-commit-graph.txt: typeset more in monospace MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit While we're here, fix an instance of "folder" to be "directory". Signed-off-by: Martin Ågren Reviewed-by: Derrick Stolee Signed-off-by: Junio C Hamano --- Documentation/git-commit-graph.txt | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/Documentation/git-commit-graph.txt b/Documentation/git-commit-graph.txt index f42f2a1481..6ac610f016 100644 --- a/Documentation/git-commit-graph.txt +++ b/Documentation/git-commit-graph.txt @@ -25,9 +25,9 @@ OPTIONS --object-dir:: Use given directory for the location of packfiles and commit graph file. This parameter exists to specify the location of an alternate - that only has the objects directory, not a full .git directory. The - commit graph file is expected to be at /info/commit-graph and - the packfiles are expected to be in /pack. + that only has the objects directory, not a full `.git` directory. The + commit graph file is expected to be at `/info/commit-graph` and + the packfiles are expected to be in `/pack`. COMMANDS @@ -66,14 +66,15 @@ database. Used to check for corrupted data. EXAMPLES -------- -* Write a commit graph file for the packed commits in your local .git folder. +* Write a commit graph file for the packed commits in your local `.git` + directory. + ------------------------------------------------ $ git commit-graph write ------------------------------------------------ * Write a graph file, extending the current graph file using commits - in . + in ``. + ------------------------------------------------ $ echo | git commit-graph write --stdin-packs @@ -86,7 +87,7 @@ $ git show-ref -s | git commit-graph write --stdin-commits ------------------------------------------------ * Write a graph file containing all commits in the current - commit-graph file along with those reachable from HEAD. + commit-graph file along with those reachable from `HEAD`. + ------------------------------------------------ $ git rev-parse HEAD | git commit-graph write --stdin-commits --append From 4893d717a4e3bcb15822246d6bb2f294861b1ade Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Martin=20=C3=85gren?= Date: Thu, 27 Sep 2018 21:12:21 +0200 Subject: [PATCH 3/4] git-commit-graph.txt: refer to "*commit*-graph file" MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This document sometimes refers to the "commit-graph file" as just "the graph file". This saves a couple of words here and there at the risk of confusion. In particular, the documentation for `git commit-graph read` appears to suggest that there are indeed different types of graph files. Let's just write out the full name everywhere. The full name, by the way, is not the dash-less "commit graph file". Use the dashed form. (The next commit will fix the remaining few instances of the "commit graph file" in this document.) Signed-off-by: Martin Ågren Reviewed-by: Derrick Stolee Signed-off-by: Junio C Hamano --- Documentation/git-commit-graph.txt | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/Documentation/git-commit-graph.txt b/Documentation/git-commit-graph.txt index 6ac610f016..f33330a171 100644 --- a/Documentation/git-commit-graph.txt +++ b/Documentation/git-commit-graph.txt @@ -54,8 +54,8 @@ existing commit-graph file. 'read':: -Read a graph file given by the commit-graph file and output basic -details about the graph file. Used for debugging purposes. +Read the commit-graph file and output basic details about it. +Used for debugging purposes. 'verify':: @@ -73,20 +73,20 @@ EXAMPLES $ git commit-graph write ------------------------------------------------ -* Write a graph file, extending the current graph file using commits - in ``. +* Write a commit-graph file, extending the current commit-graph file + using commits in ``. + ------------------------------------------------ $ echo | git commit-graph write --stdin-packs ------------------------------------------------ -* Write a graph file containing all reachable commits. +* Write a commit-graph file containing all reachable commits. + ------------------------------------------------ $ git show-ref -s | git commit-graph write --stdin-commits ------------------------------------------------ -* Write a graph file containing all commits in the current +* Write a commit-graph file containing all commits in the current commit-graph file along with those reachable from `HEAD`. + ------------------------------------------------ From 4c399442f781f70a00273746ca6a0de9fef9b0d3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Martin=20=C3=85gren?= Date: Thu, 27 Sep 2018 21:12:22 +0200 Subject: [PATCH 4/4] Doc: refer to the "commit-graph file" with dash MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The file processed by `git commit-graph` is referred to as the "commit-graph file", also with a dash. We have a few references to the "commit graph file", though, without the dash. These occur in git-commit-graph.txt as well as in Doc/technical/commit-graph.txt. Fix them. Do not change the references to the "commit graph" (without "... file") as a data structure. Signed-off-by: Martin Ågren Reviewed-by: Derrick Stolee Signed-off-by: Junio C Hamano --- Documentation/git-commit-graph.txt | 12 ++++++------ Documentation/technical/commit-graph.txt | 8 ++++---- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/Documentation/git-commit-graph.txt b/Documentation/git-commit-graph.txt index f33330a171..624470e198 100644 --- a/Documentation/git-commit-graph.txt +++ b/Documentation/git-commit-graph.txt @@ -3,7 +3,7 @@ git-commit-graph(1) NAME ---- -git-commit-graph - Write and verify Git commit graph files +git-commit-graph - Write and verify Git commit-graph files SYNOPSIS @@ -17,16 +17,16 @@ SYNOPSIS DESCRIPTION ----------- -Manage the serialized commit graph file. +Manage the serialized commit-graph file. OPTIONS ------- --object-dir:: - Use given directory for the location of packfiles and commit graph + Use given directory for the location of packfiles and commit-graph file. This parameter exists to specify the location of an alternate that only has the objects directory, not a full `.git` directory. The - commit graph file is expected to be at `/info/commit-graph` and + commit-graph file is expected to be at `/info/commit-graph` and the packfiles are expected to be in `/pack`. @@ -34,7 +34,7 @@ COMMANDS -------- 'write':: -Write a commit graph file based on the commits found in packfiles. +Write a commit-graph file based on the commits found in packfiles. + With the `--stdin-packs` option, generate the new commit graph by walking objects only in the specified pack-indexes. (Cannot be combined @@ -66,7 +66,7 @@ database. Used to check for corrupted data. EXAMPLES -------- -* Write a commit graph file for the packed commits in your local `.git` +* Write a commit-graph file for the packed commits in your local `.git` directory. + ------------------------------------------------ diff --git a/Documentation/technical/commit-graph.txt b/Documentation/technical/commit-graph.txt index c664acbd76..6b7dde011e 100644 --- a/Documentation/technical/commit-graph.txt +++ b/Documentation/technical/commit-graph.txt @@ -15,13 +15,13 @@ There are two main costs here: 1. Decompressing and parsing commits. 2. Walking the entire graph to satisfy topological order constraints. -The commit graph file is a supplemental data structure that accelerates +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 as "commit-graph" either in the .git/objects/info directory or in the info directory of an alternate. -The commit graph file stores the commit graph structure along with some +The commit-graph file stores the commit graph structure along with some extra metadata to speed up graph walks. By listing commit OIDs in lexi- cographic order, we can identify an integer position for each commit and refer to the parents of a commit using those integer positions. We use @@ -103,7 +103,7 @@ that of a parent. Design Details -------------- -- The commit graph file is stored in a file named 'commit-graph' in the +- The commit-graph file is stored in a file named 'commit-graph' in the .git/objects/info directory. This could be stored in the info directory of an alternate. @@ -127,7 +127,7 @@ Future Work - 'log --topo-order' - 'tag --merged' -- A server could provide a commit graph file as part of the network protocol +- A server could provide a commit-graph file as part of the network protocol to avoid extra calculations by clients. This feature is only of benefit if the user is willing to trust the file, because verifying the file is correct is as hard as computing it from scratch.