# [PATCH 0/4] doc: fixes to gitcore-tutorial.txt 15 messages from 2016-12-09 to 2016-12-13. Participants: Kristoffer Haugsbakk, Junio C Hamano, Philip Oakley. Thread: https://gitlist.dev/t/44665 ## Kristoffer Haugsbakk, 2016-12-09 15:51 Subject: [PATCH 0/4] doc: fixes to gitcore-tutorial.txt Message-ID: <20161209155112.2112-1-kristoffer.haugsbakk@gmail.com> URL: https://gitlist.dev/e/20161209155112.2112-1-kristoffer.haugsbakk%40gmail.com ``` This series of patches attempts to fix some minor mistakes in gitcore-tutorial.txt that I found while reading it. They are all concerned with grammar and things like accidentally omitted words. I previously sent a single patch on 2016-11-04 ("[PATCH] doc: fill in omitted word"). The patch "doc: omit needless "for"" is a follow-up to that, taking into consideration the feedback from Junio C Hamano and Jeff King. Kristoffer Haugsbakk (4): doc: add articles (grammar) doc: add verb in front of command to run doc: make the intent of sentence clearer doc: omit needless "for" Documentation/gitcore-tutorial.txt | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) -- 2.11.0 ``` ## Kristoffer Haugsbakk, 2016-12-09 15:51 Subject: [PATCH 1/4] doc: add articles (grammar) Message-ID: <20161209155112.2112-2-kristoffer.haugsbakk@gmail.com> URL: https://gitlist.dev/e/20161209155112.2112-2-kristoffer.haugsbakk%40gmail.com In-Reply-To: <20161209155112.2112-1-kristoffer.haugsbakk@gmail.com> ``` Add definite and indefinite articles in three places where they were missing. - Use "the" in front of a directory name - Use "the" in front of "style of cooperation" - Use an indefinite article in front of "CVS background" Signed-off-by: Kristoffer Haugsbakk --- Documentation/gitcore-tutorial.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt index 4546fa0d7..6c434aff3 100644 --- a/Documentation/gitcore-tutorial.txt +++ b/Documentation/gitcore-tutorial.txt @@ -1368,7 +1368,7 @@ $ git repack will do it for you. If you followed the tutorial examples, you would have accumulated about 17 objects in `.git/objects/??/` directories by now. 'git repack' tells you how many objects it -packed, and stores the packed file in `.git/objects/pack` +packed, and stores the packed file in the `.git/objects/pack` directory. [NOTE] @@ -1543,9 +1543,9 @@ like this: Working with Others, Shared Repository Style -------------------------------------------- -If you are coming from CVS background, the style of cooperation +If you are coming from a CVS background, the style of cooperation suggested in the previous section may be new to you. You do not -have to worry. Git supports "shared public repository" style of +have to worry. Git supports the "shared public repository" style of cooperation you are probably more familiar with as well. See linkgit:gitcvs-migration[7] for the details. -- 2.11.0 ``` ## Kristoffer Haugsbakk, 2016-12-09 15:51 Subject: [PATCH 2/4] doc: add verb in front of command to run Message-ID: <20161209155112.2112-3-kristoffer.haugsbakk@gmail.com> URL: https://gitlist.dev/e/20161209155112.2112-3-kristoffer.haugsbakk%40gmail.com In-Reply-To: <20161209155112.2112-1-kristoffer.haugsbakk@gmail.com> ``` Instead of using the command 'git clone' as a verb, use "run" as the verb indicating the action of executing the command 'git clone'. Signed-off-by: Kristoffer Haugsbakk --- Documentation/gitcore-tutorial.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt index 6c434aff3..72ed90ca3 100644 --- a/Documentation/gitcore-tutorial.txt +++ b/Documentation/gitcore-tutorial.txt @@ -1478,7 +1478,7 @@ You can repack this private repository whenever you feel like. A recommended work cycle for a "subsystem maintainer" who works on that project and has an own "public repository" goes like this: -1. Prepare your work repository, by 'git clone' the public +1. Prepare your work repository, by running 'git clone' on the public repository of the "project lead". The URL used for the initial cloning is stored in the remote.origin.url configuration variable. -- 2.11.0 ``` ## Kristoffer Haugsbakk, 2016-12-09 15:51 Subject: [PATCH 3/4] doc: make the intent of sentence clearer Message-ID: <20161209155112.2112-4-kristoffer.haugsbakk@gmail.com> URL: https://gitlist.dev/e/20161209155112.2112-4-kristoffer.haugsbakk%40gmail.com In-Reply-To: <20161209155112.2112-1-kristoffer.haugsbakk@gmail.com> ``` By adding the word "just", which might have been accidentally omitted. Adding the word "just" makes it clear that the point is to *not* do an octopus merge simply because you *can* do it. In other words, you should have a reason for doing it beyond simply having two (seemingly) independent commits that you need to merge into another branch, since it's not always the best approach. The previous sentence made it look more like it was trying to say that you shouldn't do an octopus merge *because* you can do an octopus merge. Although this interpretation doesn't make sense and the rest of the paragraph makes the intended meaning clear, this adjustment should make the intent of the sentence more immediately clear to the reader. Signed-off-by: Kristoffer Haugsbakk --- Documentation/gitcore-tutorial.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt index 72ed90ca3..72ca9c1ef 100644 --- a/Documentation/gitcore-tutorial.txt +++ b/Documentation/gitcore-tutorial.txt @@ -1635,7 +1635,7 @@ $ git show-branch ++* [master~2] Pretty-print messages. ------------ -Note that you should not do Octopus because you can. An octopus +Note that you should not do Octopus just because you can. An octopus is a valid thing to do and often makes it easier to view the commit history if you are merging more than two independent changes at the same time. However, if you have merge conflicts -- 2.11.0 ``` ## Kristoffer Haugsbakk, 2016-12-09 15:51 Subject: [PATCH 4/4] doc: omit needless "for" Message-ID: <20161209155112.2112-5-kristoffer.haugsbakk@gmail.com> URL: https://gitlist.dev/e/20161209155112.2112-5-kristoffer.haugsbakk%40gmail.com In-Reply-To: <20161209155112.2112-1-kristoffer.haugsbakk@gmail.com> ``` What was intended was perhaps "... plumbing does for you" ("you" added), but simply omitting the word "for" is more terse and gets the intended point across just as well, if not more so. I originally went with the approach of writing "for you", but Junio C Hamano suggested this approach instead. Signed-off-by: Kristoffer Haugsbakk --- Notes (kristoffers): The original patch was sent to the mailing list on 2016-11-04, and Junio replied with his suggested correction on 2016-11-10; see the cover letter. Documentation/gitcore-tutorial.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt index 72ca9c1ef..22309cfb4 100644 --- a/Documentation/gitcore-tutorial.txt +++ b/Documentation/gitcore-tutorial.txt @@ -25,7 +25,7 @@ you want to understand Git's internals. The core Git is often called "plumbing", with the prettier user interfaces on top of it called "porcelain". You may not want to use the plumbing directly very often, but it can be good to know what the -plumbing does for when the porcelain isn't flushing. +plumbing does when the porcelain isn't flushing. Back when this document was originally written, many porcelain commands were shell scripts. For simplicity, it still uses them as -- 2.11.0 ``` ## Junio C Hamano, 2016-12-09 23:13 Subject: Re: [PATCH 0/4] doc: fixes to gitcore-tutorial.txt Message-ID: URL: https://gitlist.dev/e/xmqq1sxgr90f.fsf%40gitster.mtv.corp.google.com In-Reply-To: <20161209155112.2112-1-kristoffer.haugsbakk@gmail.com> ``` Kristoffer Haugsbakk writes: > This series of patches attempts to fix some minor mistakes in > gitcore-tutorial.txt that I found while reading it. They are all > concerned with grammar and things like accidentally omitted words. Grammar is not my forte, so even though I'll queue them as-is because I didn't spot anything wrong in them and thought they are all improvements, I'd appreciate somebody else to lend an eye or two over them. Thanks. ``` ## Philip Oakley, 2016-12-10 20:28 Subject: Re: [PATCH 1/4] doc: add articles (grammar) Message-ID: <88A192B34B3D4DDDA47628687AE458D3@PhilipOakley> URL: https://gitlist.dev/e/88A192B34B3D4DDDA47628687AE458D3%40PhilipOakley In-Reply-To: <20161209155112.2112-2-kristoffer.haugsbakk@gmail.com> ``` From: "Kristoffer Haugsbakk" Sent: Friday, December 09, 2016 3:51 PM > Add definite and indefinite articles in three places where they were > missing. > > - Use "the" in front of a directory name > - Use "the" in front of "style of cooperation" > - Use an indefinite article in front of "CVS background" > > Signed-off-by: Kristoffer Haugsbakk > --- > Documentation/gitcore-tutorial.txt | 6 +++--- > 1 file changed, 3 insertions(+), 3 deletions(-) > > diff --git a/Documentation/gitcore-tutorial.txt > b/Documentation/gitcore-tutorial.txt > index 4546fa0d7..6c434aff3 100644 > --- a/Documentation/gitcore-tutorial.txt > +++ b/Documentation/gitcore-tutorial.txt > @@ -1368,7 +1368,7 @@ $ git repack > will do it for you. If you followed the tutorial examples, you > would have accumulated about 17 objects in `.git/objects/??/` > directories by now. 'git repack' tells you how many objects it > -packed, and stores the packed file in `.git/objects/pack` > +packed, and stores the packed file in the `.git/objects/pack` > directory. > > [NOTE] > @@ -1543,9 +1543,9 @@ like this: > Working with Others, Shared Repository Style > -------------------------------------------- > > -If you are coming from CVS background, the style of cooperation > +If you are coming from a CVS background, the style of cooperation > suggested in the previous section may be new to you. You do not > -have to worry. Git supports "shared public repository" style of > +have to worry. Git supports the "shared public repository" style of > cooperation you are probably more familiar with as well. > > See linkgit:gitcvs-migration[7] for the details. > -- > 2.11.0 This looks good to me. -- Philip (UK) ``` ## Philip Oakley, 2016-12-10 20:48 Subject: Re: [PATCH 2/4] doc: add verb in front of command to run Message-ID: <2C16DAFED0D94B28AF9CE7F8BBA122F0@PhilipOakley> URL: https://gitlist.dev/e/2C16DAFED0D94B28AF9CE7F8BBA122F0%40PhilipOakley In-Reply-To: <20161209155112.2112-3-kristoffer.haugsbakk@gmail.com> ``` From: "Kristoffer Haugsbakk" Sent: Friday, December 09, 2016 3:51 PM > Instead of using the command 'git clone' as a verb, use "run" as the > verb indicating the action of executing the command 'git clone'. I would expect 'cloning' as the commonly in use verb here, with the command then quoted. > > Signed-off-by: Kristoffer Haugsbakk > --- > Documentation/gitcore-tutorial.txt | 2 +- > 1 file changed, 1 insertion(+), 1 deletion(-) > > diff --git a/Documentation/gitcore-tutorial.txt > b/Documentation/gitcore-tutorial.txt > index 6c434aff3..72ed90ca3 100644 > --- a/Documentation/gitcore-tutorial.txt > +++ b/Documentation/gitcore-tutorial.txt > @@ -1478,7 +1478,7 @@ You can repack this private repository whenever you > feel like. > A recommended work cycle for a "subsystem maintainer" who works > on that project and has an own "public repository" goes like this: > > -1. Prepare your work repository, by 'git clone' the public > +1. Prepare your work repository, by running 'git clone' on the public Perhaps ? ... by cloning ('git clone ') the public The full command is shown using the same terminology as the following line. > repository of the "project lead". The URL used for the > initial cloning is stored in the remote.origin.url > configuration variable. > -- > 2.11.0 > > -- Philip ``` ## Philip Oakley, 2016-12-10 20:52 Subject: Re: [PATCH 3/4] doc: make the intent of sentence clearer Message-ID: <34DFA15DE05248069167FE613B66CD70@PhilipOakley> URL: https://gitlist.dev/e/34DFA15DE05248069167FE613B66CD70%40PhilipOakley In-Reply-To: <20161209155112.2112-4-kristoffer.haugsbakk@gmail.com> ``` From: "Kristoffer Haugsbakk" Sent: Friday, December 09, 2016 3:51 PM > By adding the word "just", which might have been accidentally omitted. > > Adding the word "just" makes it clear that the point is to *not* do an > octopus merge simply because you *can* do it. In other words, you > should have a reason for doing it beyond simply having two (seemingly) > independent commits that you need to merge into another branch, since > it's not always the best approach. > > The previous sentence made it look more like it was trying to say that > you shouldn't do an octopus merge *because* you can do an octopus merge. > Although this interpretation doesn't make sense and the rest of the > paragraph makes the intended meaning clear, this adjustment should make > the intent of the sentence more immediately clear to the reader. > > Signed-off-by: Kristoffer Haugsbakk > --- > Documentation/gitcore-tutorial.txt | 2 +- > 1 file changed, 1 insertion(+), 1 deletion(-) > > diff --git a/Documentation/gitcore-tutorial.txt > b/Documentation/gitcore-tutorial.txt > index 72ed90ca3..72ca9c1ef 100644 > --- a/Documentation/gitcore-tutorial.txt > +++ b/Documentation/gitcore-tutorial.txt > @@ -1635,7 +1635,7 @@ $ git show-branch > ++* [master~2] Pretty-print messages. > ------------ > > -Note that you should not do Octopus because you can. An octopus > +Note that you should not do Octopus just because you can. An octopus > is a valid thing to do and often makes it easier to view the > commit history if you are merging more than two independent > changes at the same time. However, if you have merge conflicts > -- > 2.11.0 > Looks like a reasonable emphasis to me -- Philip (UK) ``` ## Philip Oakley, 2016-12-11 13:05 Subject: Re: [PATCH 4/4] doc: omit needless "for" Message-ID: <2645548666054ED5BD30436E9DA41C14@PhilipOakley> URL: https://gitlist.dev/e/2645548666054ED5BD30436E9DA41C14%40PhilipOakley In-Reply-To: <20161209155112.2112-5-kristoffer.haugsbakk@gmail.com> ``` From: "Kristoffer Haugsbakk" Sent: Friday, December 09, 2016 3:51 PM > What was intended was perhaps "... plumbing does for you" ("you" added), > but > simply omitting the word "for" is more terse and gets the intended point > across > just as well, if not more so. After some thought, I think the original is more 'right'. Without the 'for' it suggests that understanding individual plumbing commands would explain some issue being seen with a fancy porcelain command which they probably don't. Rather the 'for' is forward looking toward using the plumbing commands as tools to investigate and then re-plumb the aestehetics to the desired output. The whole porcelain euphemism makes for some awkward phrasing. > > I originally went with the approach of writing "for you", but Junio C > Hamano suggested this approach instead. > > Signed-off-by: Kristoffer Haugsbakk > --- > > Notes (kristoffers): > The original patch was sent to the mailing list on 2016-11-04, and > Junio > replied with his suggested correction on 2016-11-10; see the cover > letter. > > Documentation/gitcore-tutorial.txt | 2 +- > 1 file changed, 1 insertion(+), 1 deletion(-) > > diff --git a/Documentation/gitcore-tutorial.txt > b/Documentation/gitcore-tutorial.txt > index 72ca9c1ef..22309cfb4 100644 > --- a/Documentation/gitcore-tutorial.txt > +++ b/Documentation/gitcore-tutorial.txt > @@ -25,7 +25,7 @@ you want to understand Git's internals. > The core Git is often called "plumbing", with the prettier user If we are tidying up here, then perhaps s/core Git is often/Git commands are often/ to better clarify what aspects are plumbing / porcelain. > interfaces on top of it called "porcelain". You may not want to use the > plumbing directly very often, but it can be good to know what the > -plumbing does for when the porcelain isn't flushing. > +plumbing does when the porcelain isn't flushing. I'm not so sure that the direct allusion to 'flushing' is exactly the right tone. Part of the issue is the 'porcelain' is the initial euphemism. The other part is that both porcelain and plumbing commands have the same level of CLI un-prettiness, so the distinction isn't there. In the end I strung together: " The core Git commands are often called "plumbing", while those with the prettier user friendly output are called "porcelain". You may not want to use the plumbing directly very often, but it can be good to know what the plumbing does when either the porcelain isn't flushing, or different output aethetics are desired. " Though having both prettier and friendly in the same phrase maybe overkill. > > Back when this document was originally written, many porcelain > commands were shell scripts. For simplicity, it still uses them as > -- > 2.11.0 > -- Philip ``` ## Philip Oakley, 2016-12-11 14:09 Subject: Re: [PATCH 4/4] doc: omit needless "for" Message-ID: URL: https://gitlist.dev/e/C42D5B32E3FC43F8933D3F66CB2456C7%40PhilipOakley In-Reply-To: <2645548666054ED5BD30436E9DA41C14@PhilipOakley> ``` From: "Philip Oakley" >> diff --git a/Documentation/gitcore-tutorial.txt >> b/Documentation/gitcore-tutorial.txt >> index 72ca9c1ef..22309cfb4 100644 >> --- a/Documentation/gitcore-tutorial.txt >> +++ b/Documentation/gitcore-tutorial.txt >> @@ -25,7 +25,7 @@ you want to understand Git's internals. >> The core Git is often called "plumbing", with the prettier user > > If we are tidying up here, then perhaps > s/core Git is often/Git commands are often/ > to better clarify what aspects are plumbing / porcelain. > accidentally dropped a word. Should have said s/core Git is often/core Git commands are often/ ``` ## Kristoffer Haugsbakk, 2016-12-13 13:05 Subject: Re: [PATCH 1/4] doc: add articles (grammar) Message-ID: <8737hsj7wp.fsf@gmail.com> URL: https://gitlist.dev/e/8737hsj7wp.fsf%40gmail.com In-Reply-To: <88A192B34B3D4DDDA47628687AE458D3@PhilipOakley> ``` Thank you for reviewing this series, Philip. Philip Oakley writes: > This looks good to me. I'll add this header: Acked-by: Philip Oakley To the commit message of this patch in the next review round (version 2 of the patch series). Let me know if I should add another header, or do something different than this. -- Kristoffer Haugsbakk ``` ## Kristoffer Haugsbakk, 2016-12-13 13:23 Subject: Re: [PATCH 3/4] doc: make the intent of sentence clearer Message-ID: <871sxcj72y.fsf@gmail.com> URL: https://gitlist.dev/e/871sxcj72y.fsf%40gmail.com In-Reply-To: <34DFA15DE05248069167FE613B66CD70@PhilipOakley> ``` Philip Oakley writes: > Looks like a reasonable emphasis to me I'll add this header: Acked-by: Philip Oakley To the commit message of this patch in the next review round (version 2 of the patch series). Let me know if I should add another header, or do something different than this. -- Kristoffer Haugsbakk ``` ## Junio C Hamano, 2016-12-13 18:11 Subject: Re: [PATCH 1/4] doc: add articles (grammar) Message-ID: URL: https://gitlist.dev/e/xmqqoa0f4s2v.fsf%40gitster.mtv.corp.google.com In-Reply-To: <8737hsj7wp.fsf@gmail.com> ``` Kristoffer Haugsbakk writes: > Thank you for reviewing this series, Philip. > > Philip Oakley writes: > >> This looks good to me. > > I'll add this header: > > Acked-by: Philip Oakley > > To the commit message of this patch in the next review round (version 2 > of the patch series). > > Let me know if I should add another header, or do something different > than this. I was planning to merge all four from you as-is to 'next' today, though. Should I wait? ``` ## Kristoffer Haugsbakk, 2016-12-13 21:34 Subject: Re: [PATCH 1/4] doc: add articles (grammar) Message-ID: <87y3zjikdd.fsf@gmail.com> URL: https://gitlist.dev/e/87y3zjikdd.fsf%40gmail.com In-Reply-To: ``` Junio C Hamano writes: > I was planning to merge all four from you as-is to 'next' today, > though. Should I wait? I'll definitely defer to whatever you think is best. I guess it depends on whether you are interested in Philip Oakley's suggestions. I sent those emails to inform about what I intended to do in the next round, if it got to that point, since I haven't tried to contribute to such an organised project before. So I was informing about my assumptions about how to deal with "looks good to me"-kinds of feedback. So for my part, I'm happy with iterating on this (perhaps just adding the two "acks", or also replying to the suggestions), or just merging it as-is. -- Kristoffer Haugsbakk ```