Patch to tutorial.txt

Patch to tutorial.txt

[Paolo Ciarrocchi]

Hi all,
I'm reading the tutorial and trying to improve it while studying git.

First attempt here:
From 0b98769dfe16e3ba8cde698b75cb1067658c38e7 Mon Sep 17 00:00:00 2001
From: Paolo Ciarrocchi <paolo.ciarrocchi@gmail.com>
Date: Sun, 19 Nov 2006 23:41:31 +0100
Subject: [PATCH] One of the comment was not really clear, rephrased to
make it easier to be understood by the reader


Signed-off-by: Paolo Ciarrocchi <paolo.ciarrocchi@gmail.com>
---
 Documentation/tutorial.txt |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

diff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt
index 554ee0a..6edfb5a 100644
--- a/Documentation/tutorial.txt
+++ b/Documentation/tutorial.txt
@@ -141,7 +141,7 @@ $ git commit -a
 ------------------------------------------------

 at this point the two branches have diverged, with different changes
-made in each.  To merge the changes made in the two branches, run
+made in each.  To merge the changes made in experimental into master run

 ------------------------------------------------
 $ git pull . experimental
-- 
1.4.4.ge3d4


Regards,
-- 
Paolo
http://docs.google.com/View?docid=dhbdhs7d_4hsxqc8
http://www.linkedin.com/pub/0/132/9a3
Non credo nelle otto del mattino. Però esistono. Le otto del mattino
sono l'incontrovertibile prova della presenza del male nel mondo.

Re: Patch to tutorial.txt

[Jakub Narebski]

Paolo Ciarrocchi wrote:

> From 0b98769dfe16e3ba8cde698b75cb1067658c38e7 Mon Sep 17 00:00:00 2001

I think you should remove this line.

> From: Paolo Ciarrocchi <paolo.ciarrocchi@gmail.com>
> Date: Sun, 19 Nov 2006 23:41:31 +0100
> Subject: [PATCH] One of the comment was not really clear, rephrased to
> make it easier to be understood by the reader

Wordwrap. Perhaps it would be better to split description into short line,
and two-line description.

[...]
>  ------------------------------------------------
> 
>  at this point the two branches have diverged, with different changes
> -made in each.  To merge the changes made in the two branches, run
> +made in each.  To merge the changes made in experimental into master run

I would rather say:
  To merge the changes made in the two branches into master, run

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: Patch to tutorial.txt

[Jakub Narebski]

On Mon, 20 Nov 2006, Paolo Ciarrocchi wrote:
> On 11/19/06, Jakub Narebski <jnareb@gmail.com> wrote:
>> Paolo Ciarrocchi wrote:

>>> From: Paolo Ciarrocchi <paolo.ciarrocchi@gmail.com>
>>> Date: Sun, 19 Nov 2006 23:41:31 +0100
>>> Subject: [PATCH] One of the comment was not really clear, rephrased to
>>> make it easier to be understood by the reader
>>
>> Wordwrap. Perhaps it would be better to split description into short line,
>> and two-line description.

See http://git.or.cz/gitwiki/CommitMessageConventions

In short, it is better to split description into short one-line
description, for example
  "Documentation: Make comment about merging in tutorial.txt more clear"
followed by empty line, then longer description of changes (if any), for
example

  One of the comment was not really clear, rephrased to make it easier
  to be understood by the reader

followed by empty line, then signoff line, for example

  Signed-off-by: Paolo Ciarrocchi <paolo.ciarrocchi@gmail.com>

> This is not clear to me, when I do a "git commit -a" I can add a text using vi,
> should I manually split the text in multiple lines?
> Only the first line will be part of the Subject?

Yes. The rest will be in the email body.
 
>> [...]
>>>  ------------------------------------------------
>>>
>>>  at this point the two branches have diverged, with different changes
>>> -made in each.  To merge the changes made in the two branches, run
>>> +made in each.  To merge the changes made in experimental into master run
>>
>> I would rather say:
>>   To merge the changes made in the two branches into master, run
> 
> Why Jakub? There are only two branches, master and experimental.
> While sitting in master and doing git pull . experimental I would
> expect to merge I did in experimental into master. Changes did in
> master are alreay merged in master. Am I wrong?

For me, "merge" in "to merge the changes" phrase is merge in common-sense
meaning of the world, not the SCM jargon. Merge the changes == join the
changes, so you have to give both sides, both changes you join.

Merge the changes == take changes in branch 'experimental' since forking,
take changes in branch 'master' since forking, join those changes
together (merge), and put the result of this joining (this merge) into
branch 'master'.

On the contrary, in "merge branch 'experimenta' into 'master'" phrase
"merge" is in the SCM meaning of this word.


Just my 2 eurocoents of not native English speaker...
-- 
Jakub Narebski

Re: Patch to tutorial.txt

[Paolo Ciarrocchi]

On 11/20/06, Jakub Narebski <jnareb@gmail.com> wrote:
> On Mon, 20 Nov 2006, Paolo Ciarrocchi wrote:
> > On 11/19/06, Jakub Narebski <jnareb@gmail.com> wrote:
> >> Paolo Ciarrocchi wrote:
>
> >>> From: Paolo Ciarrocchi <paolo.ciarrocchi@gmail.com>
> >>> Date: Sun, 19 Nov 2006 23:41:31 +0100
> >>> Subject: [PATCH] One of the comment was not really clear, rephrased to
> >>> make it easier to be understood by the reader
> >>
> >> Wordwrap. Perhaps it would be better to split description into short line,
> >> and two-line description.
>
> See http://git.or.cz/gitwiki/CommitMessageConventions

Thanks! I was not aware of that.

> In short, it is better to split description into short one-line
> description, for example
>   "Documentation: Make comment about merging in tutorial.txt more clear"
> followed by empty line, then longer description of changes (if any), for
> example
>
>   One of the comment was not really clear, rephrased to make it easier
>   to be understood by the reader
>
> followed by empty line, then signoff line, for example
>
>   Signed-off-by: Paolo Ciarrocchi <paolo.ciarrocchi@gmail.com>

Ok, but the Signed/off-by part should handled  by the -s option in
git-format-patch.

> > This is not clear to me, when I do a "git commit -a" I can add a text using vi,
> > should I manually split the text in multiple lines?
> > Only the first line will be part of the Subject?
>
> Yes. The rest will be in the email body.
>
> >> [...]
> >>>  ------------------------------------------------
> >>>
> >>>  at this point the two branches have diverged, with different changes
> >>> -made in each.  To merge the changes made in the two branches, run
> >>> +made in each.  To merge the changes made in experimental into master run
> >>
> >> I would rather say:
> >>   To merge the changes made in the two branches into master, run
> >
> > Why Jakub? There are only two branches, master and experimental.
> > While sitting in master and doing git pull . experimental I would
> > expect to merge I did in experimental into master. Changes did in
> > master are alreay merged in master. Am I wrong?
>
> For me, "merge" in "to merge the changes" phrase is merge in common-sense
> meaning of the world, not the SCM jargon. Merge the changes == join the
> changes, so you have to give both sides, both changes you join.
>
> Merge the changes == take changes in branch 'experimental' since forking,
> take changes in branch 'master' since forking, join those changes
> together (merge), and put the result of this joining (this merge) into
> branch 'master'.
>
> On the contrary, in "merge branch 'experimenta' into 'master'" phrase
> "merge" is in the SCM meaning of this word.
>
>
> Just my 2 eurocoents of not native English speaker...

I'm not a native English speaker as well, furthemore I'm still not
confident with git so your comments are more then appreciated!

Ciao,
-- 
Paolo
http://docs.google.com/View?docid=dhbdhs7d_4hsxqc8
http://www.linkedin.com/pub/0/132/9a3
Non credo nelle otto del mattino. Però esistono. Le otto del mattino
sono l'incontrovertibile prova della presenza del male nel mondo.

Re: Patch to tutorial.txt

[Jakub Narebski]

Paolo Ciarrocchi wrote:
> On 11/20/06, Jakub Narebski <jnareb@gmail.com> wrote:
>
>> followed by empty line, then signoff line, for example
>>
>>   Signed-off-by: Paolo Ciarrocchi <paolo.ciarrocchi@gmail.com>
> 
> Ok, but the Signed/off-by part should handled by the -s option in
> git-format-patch.

Signed-off-by _can_ be added by -s option in git-format-patch, but 
I think it is usually better to have it added in the commit, by the -s 
option to git-commit.

-- 
Jakub Narebski

Re: Patch to tutorial.txt

[Paolo Ciarrocchi]

On 11/20/06, Jakub Narebski <jnareb@gmail.com> wrote:
> Paolo Ciarrocchi wrote:
> > On 11/20/06, Jakub Narebski <jnareb@gmail.com> wrote:
> >
> >> followed by empty line, then signoff line, for example
> >>
> >>   Signed-off-by: Paolo Ciarrocchi <paolo.ciarrocchi@gmail.com>
> >
> > Ok, but the Signed/off-by part should handled by the -s option in
> > git-format-patch.
>
> Signed-off-by _can_ be added by -s option in git-format-patch, but
> I think it is usually better to have it added in the commit, by the -s
> option to git-commit.

Oh, I wan not aware of that as well. Maybe it's worth to be mentioned
in the tutorial.

I'll properly redo the patch later today or tomorrow.

Thanks!
Ciao,
-- 
Paolo
http://docs.google.com/View?docid=dhbdhs7d_4hsxqc8
http://www.linkedin.com/pub/0/132/9a3
Non credo nelle otto del mattino. Però esistono. Le otto del mattino
sono l'incontrovertibile prova della presenza del male nel mondo.

Re: Patch to tutorial.txt

[Petr Baudis]

On Mon, Nov 20, 2006 at 09:49:31AM CET, Jakub Narebski wrote:
> On Mon, 20 Nov 2006, Paolo Ciarrocchi wrote:
> > On 11/19/06, Jakub Narebski <jnareb@gmail.com> wrote:
> >> Paolo Ciarrocchi wrote:
> >> [...]
> >>>  ------------------------------------------------
> >>>
> >>>  at this point the two branches have diverged, with different changes
> >>> -made in each.  To merge the changes made in the two branches, run
> >>> +made in each.  To merge the changes made in experimental into master run
> >>
> >> I would rather say:
> >>   To merge the changes made in the two branches into master, run
> > 
> > Why Jakub? There are only two branches, master and experimental.
> > While sitting in master and doing git pull . experimental I would
> > expect to merge I did in experimental into master. Changes did in
> > master are alreay merged in master. Am I wrong?
> 
> For me, "merge" in "to merge the changes" phrase is merge in common-sense
> meaning of the world, not the SCM jargon. Merge the changes == join the
> changes, so you have to give both sides, both changes you join.
> 
> Merge the changes == take changes in branch 'experimental' since forking,
> take changes in branch 'master' since forking, join those changes
> together (merge), and put the result of this joining (this merge) into
> branch 'master'.
> 
> On the contrary, in "merge branch 'experimenta' into 'master'" phrase
> "merge" is in the SCM meaning of this word.

I personally find the SVM meaning much less confusing, but I can't tell
how much I've been contaminated already - "merge in the two branches
into master" really strongly suggests to me that it's about some _other_
two branches.

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
The meaning of Stonehenge in Traflamadorian, when viewed from above, is:
"Replacement part being rushed with all possible speed."

Re: Patch to tutorial.txt

[Alan Chandler]

On Monday 20 November 2006 08:49, Jakub Narebski wrote:
> On Mon, 20 Nov 2006, Paolo Ciarrocchi wrote:
> >>> -made in each.  To merge the changes made in the two branches, run
> >>> +made in each.  To merge the changes made in experimental into master

> >> I would rather say:
> >>   To merge the changes made in the two branches into master, run
> >
> > Why Jakub? There are only two branches, master and experimental.
> > While sitting in master and doing git pull . experimental I would
> > expect to merge I did in experimental into master. Changes did in
> > master are alreay merged in master. Am I wrong?
>
> For me, "merge" in "to merge the changes" phrase is merge in common-sense
> meaning of the world, not the SCM jargon. Merge the changes == join the
> changes, so you have to give both sides, both changes you join.
>
> Merge the changes == take changes in branch 'experimental' since forking,
> take changes in branch 'master' since forking, join those changes
> together (merge), and put the result of this joining (this merge) into
> branch 'master'.
>
> On the contrary, in "merge branch 'experimenta' into 'master'" phrase
> "merge" is in the SCM meaning of this word.
>
>
> Just my 2 eurocoents of not native English speaker...

As a native English speaker the way the tutorial was before any of these 
changes meant that the contents of experimental and master had merged into 
one, but there was not specific indication of where this merged result had 
been put 

From _your_ phrasing I took the meaning that there were two independent 
branches which then got merged into master although that leaves me puzzled 
because there is only one other independant branch and thats the experimental 
one 

I think the wording Paolo used is clearer and precisely right - we are merging 
the experimental stuff into master and experimental remains as it was 
(although in a fast forward experimental and master end up the same - this is 
not true in the example in the tutorial which says that changes are made on 
both branches).



-- 
Alan Chandler