git-commit-graph.txt: various cleanups
cover git-commit-graph.txt: various cleanups
The first patch is a bug-fix. The second applies some more monospace-ing, which should also be good thing.
The last two patches are based on my understanding that git commit-graph handles the "commit graph file", without a dash. If that's correct, there might be more such cleanups to be made in other parts of git.git. If the dash should actually be there, I could do these changes in the other direction. Or maybe dash-vs-no-dash is not an actual problem at all...
Martin
Martin Ågren (4):
git-commit-graph.txt: fix bullet lists git-commit-graph.txt: typeset more in monospace git-commit-graph.txt: refer to "*commit* graph file" git-commit-graph.txt: refer to the "commit graph file" without dash
Documentation/git-commit-graph.txt | 29 +++++++++++++++-------------- 1 file changed, 15 insertions(+), 14 deletions(-)
Signature · 1 line
2.19.0.216.g2d3b1c576c
PATCH 1/4 git-commit-graph.txt: fix bullet lists
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 *.
--- Documentation/git-commit-graph.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)
Documentation/git-commit-graph.txt +2 -2
@@ -73,7 +73,7 @@ $ git commit-graph write ------------------------------------------------ * Write a graph file, extending the current graph file using commits -* in <pack-index>. + in <pack-index>. + ------------------------------------------------ $ echo <pack-index> | 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
Signature · 1 line
2.19.0.216.g2d3b1c576c
Re: [PATCH 1/4] git-commit-graph.txt: fix bullet lists
Quoted 4 lines · Martin Ågren
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*.
Thank you for noticing this. It clearly looks wrong at https://git-scm.com/docs/git-commit-graph
-Stolee
PATCH 2/4 git-commit-graph.txt: typeset more in monospace
In reply to Martin ÅgrenWhile we're here, fix an instance of "folder" to be "directory".
--- Documentation/git-commit-graph.txt | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-)
Documentation/git-commit-graph.txt +7 -6
@@ -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 <dir>/info/commit-graph and - the packfiles are expected to be in <dir>/pack. + that only has the objects directory, not a full `.git` directory. The + commit graph file is expected to be at `<dir>/info/commit-graph` and + the packfiles are expected to be in `<dir>/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 <pack-index>. + in `<pack-index>`. + ------------------------------------------------ $ echo <pack-index> | 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
Signature · 1 line
2.19.0.216.g2d3b1c576c
Re: [PATCH 2/4] git-commit-graph.txt: typeset more in monospace
Quoted 1 line · Martin Ågren
While we're here, fix an instance of "folder" to be "directory".
These changes are clearly good. Thanks!
PATCH 3/4 git-commit-graph.txt: refer to "*commit* graph file"
In reply to Martin ÅgrenThis 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 "commit-graph file" with a dash, cf. the synopsis. Use the dashless form. (The next commit will fix the remaining few instances of the "commit-graph file" in this document.)
--- Documentation/git-commit-graph.txt | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-)
Documentation/git-commit-graph.txt +7 -7
@@ -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,21 +73,21 @@ EXAMPLES $ git commit-graph write ------------------------------------------------ -* Write a graph file, extending the current graph file using commits - in `<pack-index>`. +* Write a commit graph file, extending the current commit graph file + using commits in `<pack-index>`. + ------------------------------------------------ $ echo <pack-index> | 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 - commit-graph file along with those reachable from `HEAD`. +* Write a commit graph file containing all commits in the current + commit graph file along with those reachable from `HEAD`. + ------------------------------------------------ $ git rev-parse HEAD | git commit-graph write --stdin-commits --append
Signature · 1 line
2.19.0.216.g2d3b1c576c
Re: [PATCH 3/4] git-commit-graph.txt: refer to "*commit* graph file"
Quoted 6 lines · Martin Ågren
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 readappears to suggest that there are indeed different types of graph files.Let's just write out the full name everywhere.
This is a good idea. Let's be specific.
Quoted 3 lines
The full name, by the way, is not the "commit-graph file" with a dash, cf. the synopsis. Use the dashless form. (The next commit will fix the remaining few instances of the "commit-graph file" in this document.)
The file is literally at ".git/objects/info/commit-graph" which is why I tried to use "commit-graph" everywhere. Why do you think that "commit graph" is better?
Thanks,
-Stolee
Re: [PATCH 3/4] git-commit-graph.txt: refer to "*commit* graph file"
Quoted 9 lines · Derrick Stolee
Quoted 3 lines · Martin Ågren
The full name, by the way, is not the "commit-graph file" with a dash, cf. the synopsis. Use the dashless form. (The next commit will fix the remaining few instances of the "commit-graph file" in this document.)
The file is literally at ".git/objects/info/commit-graph" which is why I tried to use "commit-graph" everywhere. Why do you think that "commit graph" is better?
I noticed the discrepancy between "commit graph file" and "commit-graph file" and briefly wondered if it was intentional, i.e., if it meant anything, but the dash vs no dash seemed pretty random to me. In order to figure out which was (more) correct, I went to the synopsis. But admittedly, that was quite arbitrary. For all I know, "the commit-graph file" could be the better choice, grammatically.
There is the file named "commit-graph" as you note, but it might on the other hand just as well be called "cg.bin". I would probably try to let the filename "commit-graph" influence the user manual only if we would have written "cg.bin" instead. For example, if we would talk about how you might get out of a hole by deleting the "<...>/commit-graph" ("cg.bin") file manually.
But that's certainly not to argue against "the commit-graph file". I'd be happy to s/commit graph file/commit-graph file/g instead to keep others from wondering if these are two slightly different things. And if the concept and the file have the same name, all the better.
If you agree, I'll do that in a v2, where I will also note in the Options section that --object-dir takes a <dir>.
Martin
Re: [PATCH 3/4] git-commit-graph.txt: refer to "*commit* graph file"
Quoted 8 lines · Martin Ågren
Quoted 7 lines · Derrick Stolee
Quoted 3 lines · Martin Ågren
The full name, by the way, is not the "commit-graph file" with a dash, cf. the synopsis. Use the dashless form. (The next commit will fix the remaining few instances of the "commit-graph file" in this document.)
The file is literally at ".git/objects/info/commit-graph" which is why I tried to use "commit-graph" everywhere. Why do you think that "commit graph" is better?
Quoted 6 lines
I noticed the discrepancy between "commit graph file" and "commit-graph file" and briefly wondered if it was intentional, i.e., if it meant anything, but the dash vs no dash seemed pretty random to me. In order to figure out which was (more) correct, I went to the synopsis. But admittedly, that was quite arbitrary. For all I know, "the commit-graph file" could be the better choice, grammatically.
Yeah, the fact that I was inconsistent forced you to make a choice. Sorry for that.
Quoted 7 lines
There is the file named "commit-graph" as you note, but it might on the other hand just as well be called "cg.bin". I would probably try to let the filename "commit-graph" influence the user manual only if we would have written "cg.bin" instead. For example, if we would talk about how you might get out of a hole by deleting the "<...>/commit-graph" ("cg.bin") file manually.
Quoted 7 lines
But that's certainly not to argue against "the commit-graph file". I'd be happy to s/commit graph file/commit-graph file/g instead to keep others from wondering if these are two slightly different things. And if the concept and the file have the same name, all the better.
If you agree, I'll do that in a v2, where I will also note in the Options section that
--object-dirtakes a<dir>.
I think "commit-graph" is better. Thanks for also catching the ... formatting.
Thanks!
-Stolee
v2 cover git-commit-graph.txt: various cleanups
This v2 starts with the same two patches as v1 did, then goes on to change "[commit] graph file" to "commit-graph file" with a dash, to match other instances as well as Derrick's feedback.
Martin Ågren (4):
git-commit-graph.txt: fix bullet lists git-commit-graph.txt: typeset more in monospace git-commit-graph.txt: refer to "*commit*-graph file"
Doc: refer to the "commit-graph file" with dash
Documentation/git-commit-graph.txt | 31 ++++++++++++------------ Documentation/technical/commit-graph.txt | 8 +++--- 2 files changed, 20 insertions(+), 19 deletions(-)
Range-diff against v1:
1: 222721870b = 1: 837ef2f231 git-commit-graph.txt: fix bullet lists 2: acac5c3584 = 2: 9759a162ca git-commit-graph.txt: typeset more in monospace 3: 65f42c947a ! 3: 759bc886d8 git-commit-graph.txt: refer to "*commit* graph file"
@@ -1,17 +1,17 @@
Author: Martin Ågren <[email protected]>
- git-commit-graph.txt: refer to "*commit* graph file"
+ git-commit-graph.txt: refer to "*commit*-graph file"
- This document sometimes refers to the "commit graph file" as just "the
+ 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 "commit-graph file" with a dash,
- cf. the synopsis. Use the dashless form. (The next commit will fix the
- remaining few instances of the "commit-graph file" in this document.)
+ 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.)
@@ -24,7 +24,7 @@
-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. ++Read the commit-graph file and output basic details about it.
+Used for debugging purposes.
'verify'::
@@ -35,7 +35,7 @@
-* Write a graph file, extending the current graph file using commits
- in <pack-index>.
-+* Write a commit graph file, extending the current commit graph file ++* Write a commit-graph file, extending the current commit-graph file
+ using commits in <pack-index>.
+
------------------------------------------------
@@ -43,16 +43,14 @@
------------------------------------------------
-* Write a graph file containing all reachable commits.
-+* Write a commit 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
-- commit-graph file along with those reachable from HEAD. -+* Write a commit graph file containing all commits in the current -+ commit graph file along with those reachable from HEAD. ++* Write a commit-graph file containing all commits in the current
+ commit-graph file along with those reachable from HEAD.
+
------------------------------------------------
- $ git rev-parse HEAD | git commit-graph write --stdin-commits --append
4: fc81147ea4 < -: ---------- git-commit-graph.txt: refer to the "commit graph file" without dash -: ---------- > 4: 99b64287ec Doc: refer to the "commit-graph file" with dash
Signature · 1 line
2.19.0.216.g2d3b1c576c
PATCH v2 1/4 git-commit-graph.txt: fix bullet lists
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 *.
--- Documentation/git-commit-graph.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)
Documentation/git-commit-graph.txt +2 -2
@@ -73,7 +73,7 @@ $ git commit-graph write ------------------------------------------------ * Write a graph file, extending the current graph file using commits -* in <pack-index>. + in <pack-index>. + ------------------------------------------------ $ echo <pack-index> | 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
Signature · 1 line
2.19.0.216.g2d3b1c576c
PATCH v2 2/4 git-commit-graph.txt: typeset more in monospace
In reply to Martin ÅgrenWhile we're here, fix an instance of "folder" to be "directory".
--- Documentation/git-commit-graph.txt | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-)
Documentation/git-commit-graph.txt +7 -6
@@ -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 <dir>/info/commit-graph and - the packfiles are expected to be in <dir>/pack. + that only has the objects directory, not a full `.git` directory. The + commit graph file is expected to be at `<dir>/info/commit-graph` and + the packfiles are expected to be in `<dir>/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 <pack-index>. + in `<pack-index>`. + ------------------------------------------------ $ echo <pack-index> | 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
Signature · 1 line
2.19.0.216.g2d3b1c576c
PATCH v2 3/4 git-commit-graph.txt: refer to "*commit*-graph file"
In reply to Martin ÅgrenThis 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.)
--- Documentation/git-commit-graph.txt | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-)
Documentation/git-commit-graph.txt +6 -6
@@ -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 `<pack-index>`. +* Write a commit-graph file, extending the current commit-graph file + using commits in `<pack-index>`. + ------------------------------------------------ $ echo <pack-index> | 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`. + ------------------------------------------------
Signature · 1 line
2.19.0.216.g2d3b1c576c
PATCH v2 4/4 Doc: refer to the "commit-graph file" with dash
In reply to Martin ÅgrenThe 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.
--- Documentation/git-commit-graph.txt | 12 ++++++------ Documentation/technical/commit-graph.txt | 8 ++++---- 2 files changed, 10 insertions(+), 10 deletions(-)
Documentation/git-commit-graph.txt +6 -6
@@ -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 `<dir>/info/commit-graph` and + commit-graph file is expected to be at `<dir>/info/commit-graph` and the packfiles are expected to be in `<dir>/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. + ------------------------------------------------
Documentation/technical/commit-graph.txt +4 -4
@@ -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.
Signature · 1 line
2.19.0.216.g2d3b1c576c
Quoted 3 lines · Martin Ågren
This v2 starts with the same two patches as v1 did, then goes on to change "[commit] graph file" to "commit-graph file" with a dash, to match other instances as well as Derrick's feedback.
Thanks! This version satisfies my concerns and looks good to me.
Hi Derrick
Quoted 3 lines · Derrick Stolee
Thanks! This version satisfies my concerns and looks good to me.
Reviewed-by Derrick Stolee <[email protected]>
Thanks for the spectacularly snappy review. I don't expect commit graphs to help my use cases a lot, but I still wanted to try them out a little and stumbled on the * lists. Thanks for doing this work!
Martin
PATCH 4/4 git-commit-graph.txt: refer to the "commit graph file" without dash
In reply to Martin ÅgrenThe command is git commit-graph, but the file it processes is the "commit graph file" without a dash. We have a few references to the "commit-graph file", though. Fix them.
--- Documentation/git-commit-graph.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-)
Documentation/git-commit-graph.txt +3 -3
@@ -50,7 +50,7 @@ commits starting at all refs. (Cannot be combined with `--stdin-commits` or `--stdin-packs`.) + With the `--append` option, include all commits that are present in the -existing commit-graph file. +existing commit graph file. 'read'::
@@ -59,7 +59,7 @@ Used for debugging purposes. 'verify':: -Read the commit-graph file and verify its contents against the object +Read the commit graph file and verify its contents against the object database. Used to check for corrupted data.
@@ -93,7 +93,7 @@ $ git show-ref -s | git commit-graph write --stdin-commits $ git rev-parse HEAD | git commit-graph write --stdin-commits --append ------------------------------------------------ -* Read basic information from the commit-graph file. +* Read basic information from the commit graph file. + ------------------------------------------------ $ git commit-graph read
Signature · 1 line
2.19.0.216.g2d3b1c576c