[PATCH 0/4] git-commit-graph.txt: various cleanups

[PATCH 0/4] git-commit-graph.txt: various cleanups

[Martin Ågren]

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(-)

-- 
2.19.0.216.g2d3b1c576c

[PATCH 1/4] git-commit-graph.txt: fix bullet lists

[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 `*`.

Signed-off-by: Martin Ågren <martin.agren@gmail.com>
---
 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 <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
-- 
2.19.0.216.g2d3b1c576c

[PATCH 2/4] git-commit-graph.txt: typeset more in monospace

[Martin Ågren]

While we're here, fix an instance of "folder" to be "directory".

Signed-off-by: Martin Ågren <martin.agren@gmail.com>
---
 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 <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
-- 
2.19.0.216.g2d3b1c576c

[PATCH 3/4] git-commit-graph.txt: refer to "*commit* graph file"

[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 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.)

Signed-off-by: Martin Ågren <martin.agren@gmail.com>
---
 Documentation/git-commit-graph.txt | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/Documentation/git-commit-graph.txt b/Documentation/git-commit-graph.txt
index 6ac610f016..55f63d47d9 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,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
-- 
2.19.0.216.g2d3b1c576c

[PATCH 4/4] git-commit-graph.txt: refer to the "commit graph file" without dash

[Martin Ågren]

The 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.

Signed-off-by: Martin Ågren <martin.agren@gmail.com>
---
 Documentation/git-commit-graph.txt | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-commit-graph.txt b/Documentation/git-commit-graph.txt
index 55f63d47d9..dd0a53736f 100644
--- a/Documentation/git-commit-graph.txt
+++ b/Documentation/git-commit-graph.txt
@@ -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
-- 
2.19.0.216.g2d3b1c576c

Re: [PATCH 1/4] git-commit-graph.txt: fix bullet lists

[Derrick Stolee]

On 9/19/2018 12:30 PM, Martin Ågren wrote:
> 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

Re: [PATCH 2/4] git-commit-graph.txt: typeset more in monospace

[Derrick Stolee]

On 9/19/2018 12:30 PM, Martin Ågren wrote:
> While we're here, fix an instance of "folder" to be "directory".

These changes are clearly good. Thanks!

Re: [PATCH 3/4] git-commit-graph.txt: refer to "*commit* graph file"

[Derrick Stolee]

On 9/19/2018 12:30 PM, Martin Ågren wrote:
> 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.
This is a good idea. Let's be specific.
> 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"

[Martin Ågren]

On Thu, 20 Sep 2018 at 14:50, Derrick Stolee <stolee@gmail.com> wrote:
>
> On 9/19/2018 12:30 PM, Martin Ågren wrote:
> > 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"

[Derrick Stolee]

On 9/20/2018 9:38 AM, Martin Ågren wrote:
> On Thu, 20 Sep 2018 at 14:50, Derrick Stolee <stolee@gmail.com> wrote:
>> On 9/19/2018 12:30 PM, Martin Ågren wrote:
>>> 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.

Yeah, the fact that I was inconsistent forced you to make a choice. 
Sorry for that.

> 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>`.
I think "commit-graph" is better. Thanks for also catching the `...` 
formatting.

Thanks!
-Stolee

[PATCH v2 0/4] git-commit-graph.txt: various cleanups

[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.

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 <martin.agren@gmail.com>
     
    -    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.)
     
         Signed-off-by: Martin Ågren <martin.agren@gmail.com>
     
    @@ -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
-- 
2.19.0.216.g2d3b1c576c

[PATCH v2 1/4] git-commit-graph.txt: fix bullet lists

[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 `*`.

Signed-off-by: Martin Ågren <martin.agren@gmail.com>
---
 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 <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
-- 
2.19.0.216.g2d3b1c576c

[PATCH v2 2/4] git-commit-graph.txt: typeset more in monospace

[Martin Ågren]

While we're here, fix an instance of "folder" to be "directory".

Signed-off-by: Martin Ågren <martin.agren@gmail.com>
---
 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 <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
-- 
2.19.0.216.g2d3b1c576c

[PATCH v2 3/4] git-commit-graph.txt: refer to "*commit*-graph file"

[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 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 <martin.agren@gmail.com>
---
 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 `<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`.
 +
 ------------------------------------------------
-- 
2.19.0.216.g2d3b1c576c

[PATCH v2 4/4] Doc: refer to the "commit-graph file" with dash

[Martin Ågren]

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 <martin.agren@gmail.com>
---
 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 `<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.
 +
 ------------------------------------------------
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.
-- 
2.19.0.216.g2d3b1c576c

Re: [PATCH v2 0/4] git-commit-graph.txt: various cleanups

[Derrick Stolee]

On 9/27/2018 3:12 PM, Martin Ågren wrote:
> 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.

Reviewed-by: Derrick Stolee <dstolee@microsoft.com>

Re: [PATCH v2 0/4] git-commit-graph.txt: various cleanups

[Martin Ågren]

Hi Derrick

On Thu, 27 Sep 2018 at 21:16, Derrick Stolee <stolee@gmail.com> wrote:
> Thanks! This version satisfies my concerns and looks good to me.
>
> Reviewed-by: Derrick Stolee <dstolee@microsoft.com>

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