Re: [PATCH 4/6] Documentation/git-merge.txt: improve short description in NAME

[Sergey Organov]

Junio C Hamano  writes:

> sorga...@gmail.com writes:
>
>> From: Sergey Organov 
>>
>> Old description not only raised the question of why the tool is called
>> git-merge rather than git-join, but "join histories" also sounds like
>> very simple operation, something like what "git-merge -s ours" does.
>>
>> Signed-off-by: Sergey Organov 
>> ---
>>  Documentation/git-merge.txt | 3 ++-
>>  1 file changed, 2 insertions(+), 1 deletion(-)
>>
>> diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
>> index 216d2f4..cc0329d 100644
>> --- a/Documentation/git-merge.txt
>> +++ b/Documentation/git-merge.txt
>> @@ -3,7 +3,8 @@ git-merge(1)
>>  
>>  NAME
>>  
>> -git-merge - Join two or more development histories together
>> +
>> +git-merge - Merge one or more branches to the current branch
>
> This patch, evaluated by itself, looks like a regression in that it
> tries to explain "merge" by using verb "merge", making it fuzzier to
> those who do not yet know what a "merge" is.  That was why it tried
> to explain "merge" as an operation to join histories.

My thought was that "merge", the operation, is so well-known term that
it could well go into the NAME section without explanation.

Besides:

$ man merge
NAME
   merge - three-way file merge
[...]

Uses the same pattern.

>
> However, the next one, 5/6, resurrects the "join history" in the
> description part to help them, so the damage is not so severe when
> we take them together.

Damage? In SCM world we can track the issue back to:

$ man -k rcsmerge
rcsmerge (1) - merge RCS revisions

-- Sergey

Re: [PATCH 4/6] Documentation/git-merge.txt: improve short description in NAME

[Sergey Organov]

Jeff King  writes:

> On Wed, Oct 05, 2016 at 05:46:22PM +0300, sorga...@gmail.com wrote:
>
>> diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
>> index 216d2f4..cc0329d 100644
>> --- a/Documentation/git-merge.txt
>> +++ b/Documentation/git-merge.txt
>> @@ -3,7 +3,8 @@ git-merge(1)
>>  
>>  NAME
>>  
>> -git-merge - Join two or more development histories together
>> +
>> +git-merge - Merge one or more branches to the current branch
>
> I wonder if we should be more clear that you don't have to merge a
> branch; you can merge any commit. I do agree that the original was
> unnecessarily general. And I think "the current branch" is accurate
> (technically it can be to a detached HEAD, but that is pedantry that
> doesn't need to make it into the synopsis).
>
> So maybe "Merge one or more commits into the current branch".  I guess
> that is a bit vague, too. It is really "commit tips" or "lines of
> development" that we are merging. Bringing them in of course brings in
> many commits, but the "or more" there is meant to hint at multi-parent
> merges.
>
> So perhaps "one or more branches", while not completely accurate, is the
> best we can do. I dunno.

You've basically repeated my entire line of thinking that lead to the
patch.

-- Sergey.

Re: [PATCH 4/6] Documentation/git-merge.txt: improve short description in NAME

[Jeff King]

On Wed, Oct 05, 2016 at 05:46:22PM +0300, sorga...@gmail.com wrote:

> diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
> index 216d2f4..cc0329d 100644
> --- a/Documentation/git-merge.txt
> +++ b/Documentation/git-merge.txt
> @@ -3,7 +3,8 @@ git-merge(1)
>  
>  NAME
>  
> -git-merge - Join two or more development histories together
> +
> +git-merge - Merge one or more branches to the current branch

I wonder if we should be more clear that you don't have to merge a
branch; you can merge any commit. I do agree that the original was
unnecessarily general. And I think "the current branch" is accurate
(technically it can be to a detached HEAD, but that is pedantry that
doesn't need to make it into the synopsis).

So maybe "Merge one or more commits into the current branch".  I guess
that is a bit vague, too. It is really "commit tips" or "lines of
development" that we are merging. Bringing them in of course brings in
many commits, but the "or more" there is meant to hint at multi-parent
merges.

So perhaps "one or more branches", while not completely accurate, is the
best we can do. I dunno.

-Peff

Re: [PATCH 4/6] Documentation/git-merge.txt: improve short description in NAME

[Junio C Hamano]

sorga...@gmail.com writes:

> From: Sergey Organov 
>
> Old description not only raised the question of why the tool is called
> git-merge rather than git-join, but "join histories" also sounds like
> very simple operation, something like what "git-merge -s ours" does.
>
> Signed-off-by: Sergey Organov 
> ---
>  Documentation/git-merge.txt | 3 ++-
>  1 file changed, 2 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
> index 216d2f4..cc0329d 100644
> --- a/Documentation/git-merge.txt
> +++ b/Documentation/git-merge.txt
> @@ -3,7 +3,8 @@ git-merge(1)
>  
>  NAME
>  
> -git-merge - Join two or more development histories together
> +
> +git-merge - Merge one or more branches to the current branch

This patch, evaluated by itself, looks like a regression in that it
tries to explain "merge" by using verb "merge", making it fuzzier to
those who do not yet know what a "merge" is.  That was why it tried
to explain "merge" as an operation to join histories.

However, the next one, 5/6, resurrects the "join history" in the
description part to help them, so the damage is not so severe when
we take them together.

I haven't formed firm opinion on this patch yet.

[PATCH 4/6] Documentation/git-merge.txt: improve short description in NAME

[sorganov]

From: Sergey Organov 

Old description not only raised the question of why the tool is called
git-merge rather than git-join, but "join histories" also sounds like
very simple operation, something like what "git-merge -s ours" does.

Signed-off-by: Sergey Organov 
---
 Documentation/git-merge.txt | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
index 216d2f4..cc0329d 100644
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.txt
@@ -3,7 +3,8 @@ git-merge(1)
 
 NAME
 
-git-merge - Join two or more development histories together
+
+git-merge - Merge one or more branches to the current branch
 
 
 SYNOPSIS
-- 
2.10.0.1.g57b01a3