threads / discuss / 43321

Re: Patch to tutorial.txt

Subject: Re: Patch to tutorial.txt

## tl;dr

8 messages between Nov 19, 2006 and Nov 20, 2006.

replies: 7people: 4as markdown or json

Paolo Ciarrocchi· Nov 19, 2006, 22:44 UTC · lore

Patch to tutorial.txt

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.
Jakub Narebski· Nov 19, 2006, 22:59 UTC · re: Paolo Ciarrocchi · lore
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.

[...]
Show 5 quoted lines
>  ------------------------------------------------
> 
>  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
Jakub Narebski· Nov 20, 2006, 08:49 UTC · lore
On Mon, 20 Nov 2006, Paolo Ciarrocchi wrote:
> On 11/19/06, Jakub Narebski <jnareb@gmail.com> wrote:
>> Paolo Ciarrocchi wrote:
Show 7 quoted lines
>>> 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.
Show 14 quoted lines
>> [...]
>>>  ------------------------------------------------
>>>
>>>  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
Paolo Ciarrocchi· Nov 20, 2006, 09:10 UTC · re: Jakub Narebski · lore
On 11/20/06, Jakub Narebski <jnareb@gmail.com> wrote:
Show 13 quoted lines
> 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.
Show 12 quoted lines
> 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.

Show 35 quoted lines
> > 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.
Jakub Narebski· Nov 20, 2006, 09:25 UTC · re: Paolo Ciarrocchi · lore
Paolo Ciarrocchi wrote:
Show 8 quoted lines
> 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
Paolo Ciarrocchi· Nov 20, 2006, 09:34 UTC · re: Jakub Narebski · lore
On 11/20/06, Jakub Narebski <jnareb@gmail.com> wrote:
Show 13 quoted lines
> 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.
Petr Baudis· Nov 20, 2006, 13:13 UTC · re: Jakub Narebski · lore
On Mon, Nov 20, 2006 at 09:49:31AM CET, Jakub Narebski wrote:
Show 29 quoted lines
> 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."
Alan Chandler· Nov 20, 2006, 20:11 UTC · re: Jakub Narebski · lore
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
Show 22 quoted lines
> >> 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

← back to recent threads