threads / patch / 10848

patchuser-manual.txt: fix a few mistakes

Subject: [PATCH] user-manual.txt: fix a few mistakes

## tl;dr

10 messages between Nov 13, 2007 and Nov 16, 2007. Diffs are folded; open one to read it.

replies: 9people: 3as markdown or json

Sergei Organov· Nov 13, 2007, 18:19 UTC · lore
Signed-off-by: Sergei Organov <osv@javad.com>
---
 Documentation/user-manual.txt |    8 ++++----
 1 files changed, 4 insertions(+), 4 deletions(-)
Show changes to Documentation/user-manual.txt +4 −4
diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index d99adc6..a169ef0 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -475,7 +475,7 @@ Bisecting: 3537 revisions left to test after this
 If you run "git branch" at this point, you'll see that git has
 temporarily moved you to a new branch named "bisect".  This branch
 points to a commit (with commit id 65934...) that is reachable from
-v2.6.19 but not from v2.6.18.  Compile and test it, and see whether
+"master" but not from v2.6.18.  Compile and test it, and see whether
 it crashes.  Assume it does crash.  Then:
 
 -------------------------------------------------
@@ -1367,7 +1367,7 @@ If you make a commit that you later wish you hadn't, there are two
 fundamentally different ways to fix the problem:
 
 	1. You can create a new commit that undoes whatever was done
-	by the previous commit.  This is the correct thing if your
+	by the old commit.  This is the correct thing if your
 	mistake has already been made public.
 
 	2. You can go back and modify the old commit.  You should
@@ -1567,8 +1567,8 @@ old history using, for example,
 $ git log master@{1}
 -------------------------------------------------
 
-This lists the commits reachable from the previous version of the head.
-This syntax can be used to with any git command that accepts a commit,
+This lists the commits reachable from the previous version of the branch.
+This syntax can be used with any git command that accepts a commit,
 not just with git log.  Some other examples:
 
 -------------------------------------------------

-- 
1.5.3.4
Junio C Hamano· Nov 14, 2007, 07:19 UTC · re: Sergei Organov · lore

Re: [PATCH] user-manual.txt: fix a few mistakes

Sergei Organov <osv@javad.com> writes:
Show 18 quoted lines
> Signed-off-by: Sergei Organov <osv@javad.com>
> ---
>  Documentation/user-manual.txt |    8 ++++----
>  1 files changed, 4 insertions(+), 4 deletions(-)
>
> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
> index d99adc6..a169ef0 100644
> --- a/Documentation/user-manual.txt
> +++ b/Documentation/user-manual.txt
> @@ -475,7 +475,7 @@ Bisecting: 3537 revisions left to test after this
>  If you run "git branch" at this point, you'll see that git has
>  temporarily moved you to a new branch named "bisect".  This branch
>  points to a commit (with commit id 65934...) that is reachable from
> -v2.6.19 but not from v2.6.18.  Compile and test it, and see whether
> +"master" but not from v2.6.18.  Compile and test it, and see whether
>  it crashes.  Assume it does crash.  Then:
>  
>  -------------------------------------------------
Thanks.
This hunk and the last hunk I do not have any problem with.
Show 9 quoted lines
> @@ -1367,7 +1367,7 @@ If you make a commit that you later wish you hadn't, there are two
>  fundamentally different ways to fix the problem:
>  
>  	1. You can create a new commit that undoes whatever was done
> -	by the previous commit.  This is the correct thing if your
> +	by the old commit.  This is the correct thing if your
>  	mistake has already been made public.
>  
>  	2. You can go back and modify the old commit.  You should
But is this an improvement or just a churn?
Show 11 quoted lines
> @@ -1567,8 +1567,8 @@ old history using, for example,
>  $ git log master@{1}
>  -------------------------------------------------
>  
> -This lists the commits reachable from the previous version of the head.
> -This syntax can be used to with any git command that accepts a commit,
> +This lists the commits reachable from the previous version of the branch.
> +This syntax can be used with any git command that accepts a commit,
>  not just with git log.  Some other examples:
>  
>  -------------------------------------------------
Sergei Organov· Nov 14, 2007, 12:46 UTC · re: Junio C Hamano · lore

Re: [PATCH] user-manual.txt: fix a few mistakes

Junio C Hamano <gitster@pobox.com> writes:
Show 36 quoted lines
> Sergei Organov <osv@javad.com> writes:
>
>> Signed-off-by: Sergei Organov <osv@javad.com>
>> ---
>>  Documentation/user-manual.txt |    8 ++++----
>>  1 files changed, 4 insertions(+), 4 deletions(-)
>>
>> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
>> index d99adc6..a169ef0 100644
>> --- a/Documentation/user-manual.txt
>> +++ b/Documentation/user-manual.txt
>> @@ -475,7 +475,7 @@ Bisecting: 3537 revisions left to test after this
>>  If you run "git branch" at this point, you'll see that git has
>>  temporarily moved you to a new branch named "bisect".  This branch
>>  points to a commit (with commit id 65934...) that is reachable from
>> -v2.6.19 but not from v2.6.18.  Compile and test it, and see whether
>> +"master" but not from v2.6.18.  Compile and test it, and see whether
>>  it crashes.  Assume it does crash.  Then:
>>  
>>  -------------------------------------------------
>
> Thanks.
>
> This hunk and the last hunk I do not have any problem with.
>
>> @@ -1367,7 +1367,7 @@ If you make a commit that you later wish you hadn't, there are two
>>  fundamentally different ways to fix the problem:
>>  
>>  	1. You can create a new commit that undoes whatever was done
>> -	by the previous commit.  This is the correct thing if your
>> +	by the old commit.  This is the correct thing if your
>>  	mistake has already been made public.
>>  
>>  	2. You can go back and modify the old commit.  You should
>
> But is this an improvement or just a churn?

I believe this is an improvement. It's more precise. With this change it's crystal clear that both (1) and (2) above mean the same commit by calling it "the old commit". Before the change, when I read this the first time, I've got the term "previous" here literally, i.e., as the last commit made, and I thought that if the commit in question is the last one, I should do (1), otherwise -- (2). This confusion admittedly vanished rather quickly, but it did happen.

If I didn't manage to express my first impression clearly (English is not my mothers' tongue), try to read this to get similar impression:

  1. You can create a new commit that undoes whatever was done
     by the previous commit.
  2. You can go back and modify the old commit.
Do you see the problem?
-- 
Sergei.
J. Bruce Fields· Nov 14, 2007, 18:13 UTC · re: Sergei Organov · lore

Re: [PATCH] user-manual.txt: fix a few mistakes

On Wed, Nov 14, 2007 at 03:46:32PM +0300, Sergei Organov wrote:
Show 46 quoted lines
> Junio C Hamano <gitster@pobox.com> writes:
> 
> > Sergei Organov <osv@javad.com> writes:
> >
> >> Signed-off-by: Sergei Organov <osv@javad.com>
> >> ---
> >>  Documentation/user-manual.txt |    8 ++++----
> >>  1 files changed, 4 insertions(+), 4 deletions(-)
> >>
> >> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
> >> index d99adc6..a169ef0 100644
> >> --- a/Documentation/user-manual.txt
> >> +++ b/Documentation/user-manual.txt
> >> @@ -475,7 +475,7 @@ Bisecting: 3537 revisions left to test after this
> >>  If you run "git branch" at this point, you'll see that git has
> >>  temporarily moved you to a new branch named "bisect".  This branch
> >>  points to a commit (with commit id 65934...) that is reachable from
> >> -v2.6.19 but not from v2.6.18.  Compile and test it, and see whether
> >> +"master" but not from v2.6.18.  Compile and test it, and see whether
> >>  it crashes.  Assume it does crash.  Then:
> >>  
> >>  -------------------------------------------------
> >
> > Thanks.
> >
> > This hunk and the last hunk I do not have any problem with.
> >
> >> @@ -1367,7 +1367,7 @@ If you make a commit that you later wish you hadn't, there are two
> >>  fundamentally different ways to fix the problem:
> >>  
> >>  	1. You can create a new commit that undoes whatever was done
> >> -	by the previous commit.  This is the correct thing if your
> >> +	by the old commit.  This is the correct thing if your
> >>  	mistake has already been made public.
> >>  
> >>  	2. You can go back and modify the old commit.  You should
> >
> > But is this an improvement or just a churn?
> 
> I believe this is an improvement. It's more precise. With this change
> it's crystal clear that both (1) and (2) above mean the same commit by
> calling it "the old commit". Before the change, when I read this the
> first time, I've got the term "previous" here literally, i.e., as the
> last commit made, and I thought that if the commit in question is the
> last one, I should do (1), otherwise -- (2). This confusion admittedly
> vanished rather quickly, but it did happen.
I think it's a good fix, yes, thanks.--b.
J. Bruce Fields· Nov 14, 2007, 18:18 UTC · re: Sergei Organov · lore

Re: [PATCH] user-manual.txt: fix a few mistakes

On Tue, Nov 13, 2007 at 09:19:39PM +0300, Sergei Organov wrote:
Show 34 quoted lines
> 
> Signed-off-by: Sergei Organov <osv@javad.com>
> ---
>  Documentation/user-manual.txt |    8 ++++----
>  1 files changed, 4 insertions(+), 4 deletions(-)
> 
> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
> index d99adc6..a169ef0 100644
> --- a/Documentation/user-manual.txt
> +++ b/Documentation/user-manual.txt
> @@ -475,7 +475,7 @@ Bisecting: 3537 revisions left to test after this
>  If you run "git branch" at this point, you'll see that git has
>  temporarily moved you to a new branch named "bisect".  This branch
>  points to a commit (with commit id 65934...) that is reachable from
> -v2.6.19 but not from v2.6.18.  Compile and test it, and see whether
> +"master" but not from v2.6.18.  Compile and test it, and see whether
>  it crashes.  Assume it does crash.  Then:
>  
>  -------------------------------------------------
> @@ -1367,7 +1367,7 @@ If you make a commit that you later wish you hadn't, there are two
>  fundamentally different ways to fix the problem:
>  
>  	1. You can create a new commit that undoes whatever was done
> -	by the previous commit.  This is the correct thing if your
> +	by the old commit.  This is the correct thing if your
>  	mistake has already been made public.
>  
>  	2. You can go back and modify the old commit.  You should
> @@ -1567,8 +1567,8 @@ old history using, for example,
>  $ git log master@{1}
>  -------------------------------------------------
>  
> -This lists the commits reachable from the previous version of the head.
> -This syntax can be used to with any git command that accepts a commit,
I actually prefer "head" here.  On something like:
		 A--B--C
		/
	o--o--o
		\
		 o--o--o

The term "branch" could be used to refer to the whole line of development consisting of A, B, and C. The term "head", on the other hand, refers to either C or a ref that points to it. We also use the terms "branch head" or just "branch" for that case, but I think "head" is more precise.

> +This lists the commits reachable from the previous version of the branch.
> +This syntax can be used with any git command that accepts a commit,
>  not just with git log.  Some other examples:
(Otherwise looks fine, thanks!)
--b.
Junio C Hamano· Nov 14, 2007, 19:42 UTC · re: J. Bruce Fields · lore

Re: [PATCH] user-manual.txt: fix a few mistakes

"J. Bruce Fields" <bfields@fieldses.org> writes:
Show 20 quoted lines
> I actually prefer "head" here.  On something like:
>
> 		 A--B--C
> 		/
> 	o--o--o
> 		\
> 		 o--o--o
>
>
> The term "branch" could be used to refer to the whole line of
> development consisting of A, B, and C.  The term "head", on the other
> hand, refers to either C or a ref that points to it.  We also use the
> terms "branch head" or just "branch" for that case, but I think "head"
> is more precise.
>
>> +This lists the commits reachable from the previous version of the branch.
>> +This syntax can be used with any git command that accepts a commit,
>>  not just with git log.  Some other examples:
>
> (Otherwise looks fine, thanks!)

Oops, I think I skipped the hunk #2 and applied hunk #3. Will fix-up with:

-- >8 --
From: Sergei Organov <osv@javad.com>
Subject: user-manual: minor rewording for clarity.

Junio screwed up when applying the previous round of the patch; rewording from "previous" to "old" does make the description clearer.

Also revert the rewording from head to branch. The description is talking about the branch's tip commit and using the word head is clearer.

Based on input from Sergei and Bruce.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/user-manual.txt |    4 ++--
 1 files changed, 2 insertions(+), 2 deletions(-)
Show changes to Documentation/user-manual.txt +2 −2
diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 60e1385..c7cfbbc 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -1367,7 +1367,7 @@ If you make a commit that you later wish you hadn't, there are two
 fundamentally different ways to fix the problem:
 
 	1. You can create a new commit that undoes whatever was done
-	by the previous commit.  This is the correct thing if your
+	by the old commit.  This is the correct thing if your
 	mistake has already been made public.
 
 	2. You can go back and modify the old commit.  You should
@@ -1567,7 +1567,7 @@ old history using, for example,
 $ git log master@{1}
 -------------------------------------------------
 
-This lists the commits reachable from the previous version of the branch.
+This lists the commits reachable from the previous version of the head.
 This syntax can be used with any git command that accepts a commit,
 not just with git log.  Some other examples:
 

-- 
1.5.3.5.1746.g62954
J. Bruce Fields· Nov 14, 2007, 19:44 UTC · re: Junio C Hamano · lore

Re: [PATCH] user-manual.txt: fix a few mistakes

On Wed, Nov 14, 2007 at 11:42:03AM -0800, Junio C Hamano wrote:
Show 25 quoted lines
> "J. Bruce Fields" <bfields@fieldses.org> writes:
> 
> > I actually prefer "head" here.  On something like:
> >
> > 		 A--B--C
> > 		/
> > 	o--o--o
> > 		\
> > 		 o--o--o
> >
> >
> > The term "branch" could be used to refer to the whole line of
> > development consisting of A, B, and C.  The term "head", on the other
> > hand, refers to either C or a ref that points to it.  We also use the
> > terms "branch head" or just "branch" for that case, but I think "head"
> > is more precise.
> >
> >> +This lists the commits reachable from the previous version of the branch.
> >> +This syntax can be used with any git command that accepts a commit,
> >>  not just with git log.  Some other examples:
> >
> > (Otherwise looks fine, thanks!)
> 
> Oops, I think I skipped the hunk #2 and applied hunk #3.  Will
> fix-up with:
OK, thanks Junio!
--b.
Sergei Organov· Nov 15, 2007, 10:36 UTC · re: J. Bruce Fields · lore

Re: [PATCH] user-manual.txt: fix a few mistakes

"J. Bruce Fields" <bfields@fieldses.org> writes:
Show 50 quoted lines
> On Tue, Nov 13, 2007 at 09:19:39PM +0300, Sergei Organov wrote:
>> 
>> Signed-off-by: Sergei Organov <osv@javad.com>
>> ---
>>  Documentation/user-manual.txt |    8 ++++----
>>  1 files changed, 4 insertions(+), 4 deletions(-)
>> 
>> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
>> index d99adc6..a169ef0 100644
>> --- a/Documentation/user-manual.txt
>> +++ b/Documentation/user-manual.txt
>> @@ -475,7 +475,7 @@ Bisecting: 3537 revisions left to test after this
>>  If you run "git branch" at this point, you'll see that git has
>>  temporarily moved you to a new branch named "bisect".  This branch
>>  points to a commit (with commit id 65934...) that is reachable from
>> -v2.6.19 but not from v2.6.18.  Compile and test it, and see whether
>> +"master" but not from v2.6.18.  Compile and test it, and see whether
>>  it crashes.  Assume it does crash.  Then:
>>  
>>  -------------------------------------------------
>> @@ -1367,7 +1367,7 @@ If you make a commit that you later wish you hadn't, there are two
>>  fundamentally different ways to fix the problem:
>>  
>>  	1. You can create a new commit that undoes whatever was done
>> -	by the previous commit.  This is the correct thing if your
>> +	by the old commit.  This is the correct thing if your
>>  	mistake has already been made public.
>>  
>>  	2. You can go back and modify the old commit.  You should
>> @@ -1567,8 +1567,8 @@ old history using, for example,
>>  $ git log master@{1}
>>  -------------------------------------------------
>>  
>> -This lists the commits reachable from the previous version of the head.
>> -This syntax can be used to with any git command that accepts a commit,
>
> I actually prefer "head" here.  On something like:
>
> 		 A--B--C
> 		/
> 	o--o--o
> 		\
> 		 o--o--o
>
>
> The term "branch" could be used to refer to the whole line of
> development consisting of A, B, and C.  The term "head", on the other
> hand, refers to either C or a ref that points to it.  We also use the
> terms "branch head" or just "branch" for that case, but I think "head"
> is more precise.
Then I'd suggest to be precise here, e.g.:

"This lists the commits reachable from the previous version of the "master" branch head."

The real reason for me to replacing "head" with "branch" in the first place was that a few lines below there is example for HEAD, and I wanted to make it more obvious that those is entirely different.

-- 
Sergei.
J. Bruce Fields· Nov 16, 2007, 03:54 UTC · re: Sergei Organov · lore

Re: [PATCH] user-manual.txt: fix a few mistakes

On Thu, Nov 15, 2007 at 01:36:40PM +0300, Sergei Organov wrote:
Show 57 quoted lines
> "J. Bruce Fields" <bfields@fieldses.org> writes:
> 
> > On Tue, Nov 13, 2007 at 09:19:39PM +0300, Sergei Organov wrote:
> >> 
> >> Signed-off-by: Sergei Organov <osv@javad.com>
> >> ---
> >>  Documentation/user-manual.txt |    8 ++++----
> >>  1 files changed, 4 insertions(+), 4 deletions(-)
> >> 
> >> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
> >> index d99adc6..a169ef0 100644
> >> --- a/Documentation/user-manual.txt
> >> +++ b/Documentation/user-manual.txt
> >> @@ -475,7 +475,7 @@ Bisecting: 3537 revisions left to test after this
> >>  If you run "git branch" at this point, you'll see that git has
> >>  temporarily moved you to a new branch named "bisect".  This branch
> >>  points to a commit (with commit id 65934...) that is reachable from
> >> -v2.6.19 but not from v2.6.18.  Compile and test it, and see whether
> >> +"master" but not from v2.6.18.  Compile and test it, and see whether
> >>  it crashes.  Assume it does crash.  Then:
> >>  
> >>  -------------------------------------------------
> >> @@ -1367,7 +1367,7 @@ If you make a commit that you later wish you hadn't, there are two
> >>  fundamentally different ways to fix the problem:
> >>  
> >>  	1. You can create a new commit that undoes whatever was done
> >> -	by the previous commit.  This is the correct thing if your
> >> +	by the old commit.  This is the correct thing if your
> >>  	mistake has already been made public.
> >>  
> >>  	2. You can go back and modify the old commit.  You should
> >> @@ -1567,8 +1567,8 @@ old history using, for example,
> >>  $ git log master@{1}
> >>  -------------------------------------------------
> >>  
> >> -This lists the commits reachable from the previous version of the head.
> >> -This syntax can be used to with any git command that accepts a commit,
> >
> > I actually prefer "head" here.  On something like:
> >
> > 		 A--B--C
> > 		/
> > 	o--o--o
> > 		\
> > 		 o--o--o
> >
> >
> > The term "branch" could be used to refer to the whole line of
> > development consisting of A, B, and C.  The term "head", on the other
> > hand, refers to either C or a ref that points to it.  We also use the
> > terms "branch head" or just "branch" for that case, but I think "head"
> > is more precise.
> 
> Then I'd suggest to be precise here, e.g.:
> 
> "This lists the commits reachable from the previous version of the
> "master" branch head."
That sounds sensible to me, sure.
> 
> The real reason for me to replacing "head" with "branch" in the first
> place was that a few lines below there is example for HEAD, and I wanted
> to make it more obvious that those is entirely different.
OK, sure.  Thanks for the thoughtful editing!
--b.
Sergei Organov· Nov 16, 2007, 11:34 UTC · re: J. Bruce Fields · lore

Re: [PATCH] user-manual.txt: fix a few mistakes

"J. Bruce Fields" <bfields@fieldses.org> writes:
> On Thu, Nov 15, 2007 at 01:36:40PM +0300, Sergei Organov wrote:
>> "J. Bruce Fields" <bfields@fieldses.org> writes:
[...]
Show 28 quoted lines
>> >> @@ -1567,8 +1567,8 @@ old history using, for example,
>> >>  $ git log master@{1}
>> >>  -------------------------------------------------
>> >>  
>> >> -This lists the commits reachable from the previous version of the head.
>> >> -This syntax can be used to with any git command that accepts a commit,
>> >
>> > I actually prefer "head" here.  On something like:
>> >
>> > 		 A--B--C
>> > 		/
>> > 	o--o--o
>> > 		\
>> > 		 o--o--o
>> >
>> >
>> > The term "branch" could be used to refer to the whole line of
>> > development consisting of A, B, and C.  The term "head", on the other
>> > hand, refers to either C or a ref that points to it.  We also use the
>> > terms "branch head" or just "branch" for that case, but I think "head"
>> > is more precise.
>> 
>> Then I'd suggest to be precise here, e.g.:
>> 
>> "This lists the commits reachable from the previous version of the
>> "master" branch head."
>
> That sounds sensible to me, sure.
OK, I've just submitted patch for that.
-- 
Sergei.

← back to recent threads