| Message ID | 65f42c947aa2b392075740673a5dc889fd6e64e6.1537374062.git.martin.agren@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | git-commit-graph.txt: various cleanups | expand |
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
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
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
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
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(-)