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

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

[Sergei Organov]

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,
+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

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

[Junio C Hamano]

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?

> @@ -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:
>  
>  -------------------------------------------------

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

[Sergei Organov]

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.

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.

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

[J. Bruce Fields]

On Wed, Nov 14, 2007 at 03:46:32PM +0300, Sergei Organov wrote:
> 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.

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

[J. Bruce Fields]

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.

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

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

[Junio C Hamano]

"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:

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

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

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

[J. Bruce Fields]

On Wed, Nov 14, 2007 at 11:42:03AM -0800, Junio C Hamano wrote:
> "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.

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

[Sergei Organov]

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

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.

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

[J. Bruce Fields]

On Thu, Nov 15, 2007 at 01:36:40PM +0300, Sergei Organov wrote:
> "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.

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

[Sergei Organov]

"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:
[...]
>> >> @@ -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.