threads / patch / 25697

v2Documentation/git-pull: clarify configuration

Subject: [PATCH v2] Documentation/git-pull: clarify configuration

## tl;dr

6 messages between Nov 10, 2010 and Nov 11, 2010. Diffs are folded; open one to read it.

replies: 5people: 3as markdown or json

Martin von Zweigbergk· Nov 10, 2010, 07:13 UTC · lore

The sentence about 'branch.<name>.rebase' refers to the first sentence in the paragraph. Clarify by putting it in a separate paragraph.

Text provided by Jonathan Nieder.
Signed-off-by: Martin von Zweigbergk <martin.von.zweigbergk@gmail.com>
---
 Documentation/git-pull.txt |   15 +++++++++------
 1 files changed, 9 insertions(+), 6 deletions(-)
Show changes to Documentation/git-pull.txt +9 −6
diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
index c50f7dc..055126e 100644
--- a/Documentation/git-pull.txt
+++ b/Documentation/git-pull.txt
@@ -92,12 +92,15 @@ include::merge-options.txt[]
 :git-pull: 1
 
 --rebase::
-	Instead of a merge, perform a rebase after fetching.  If
-	there is a remote ref for the upstream branch, and this branch
-	was rebased since last fetched, the rebase uses that information
-	to avoid rebasing non-local changes. To make this the default
-	for branch `<name>`, set configuration `branch.<name>.rebase`
-	to `true`.
+	Instead of merging, rebase the current branch on top of the
+	upstream branch after fetching.  If there is a remote-tracking
+	branch corresponding to the upstream branch and the upstream
+	branch was rebased since last fetched, the rebase uses that
+	information to avoid rebasing non-local changes.
+
+	The default behavior is to merge rather than rebasing, but it
+	can be overridden per branch with the `branch.<name>.rebase`
+	configuration item (see git-config(1)).
 +
 [NOTE]
 This is a potentially _dangerous_ mode of operation.

-- 
1.7.3.2.167.ga361b
Jonathan Nieder· Nov 10, 2010, 17:24 UTC · re: Martin von Zweigbergk · lore

Re: [PATCH v2] Documentation/git-pull: clarify configuration

Hi again,
Martin von Zweigbergk wrote:
> The sentence about 'branch.<name>.rebase' refers to the first sentence
> in the paragraph. Clarify by putting it in a separate paragraph.
I think the patch clarifies by rewording a little, too. :)
Show 22 quoted lines
> --- a/Documentation/git-pull.txt
> +++ b/Documentation/git-pull.txt
> @@ -92,12 +92,15 @@ include::merge-options.txt[]
>  :git-pull: 1
>  
>  --rebase::
> -	Instead of a merge, perform a rebase after fetching.  If
> -	there is a remote ref for the upstream branch, and this branch
> -	was rebased since last fetched, the rebase uses that information
> -	to avoid rebasing non-local changes. To make this the default
> -	for branch `<name>`, set configuration `branch.<name>.rebase`
> -	to `true`.
> +	Instead of merging, rebase the current branch on top of the
> +	upstream branch after fetching.  If there is a remote-tracking
> +	branch corresponding to the upstream branch and the upstream
> +	branch was rebased since last fetched, the rebase uses that
> +	information to avoid rebasing non-local changes.
> +
> +	The default behavior is to merge rather than rebasing, but it
> +	can be overridden per branch with the `branch.<name>.rebase`
> +	configuration item (see git-config(1)).
>  +

Do these changes result in good output with "make -C Documentation git-pull.1" or "make -C Documentation git-pull.html"? I think it might need to be

	first paragraph
 +
 second paragraph
 +
 third paragraph
or similar.

Regards, Jonathan

Martin von Zweigbergk· Nov 11, 2010, 01:50 UTC · re: Jonathan Nieder · lore

Re: [PATCH v2] Documentation/git-pull: clarify configuration

On Wed, Nov 10, 2010 at 12:24 PM, Jonathan Nieder <jrnieder@gmail.com> wrote:
Show 8 quoted lines
> Hi again,
>
> Martin von Zweigbergk wrote:
>
>> The sentence about 'branch.<name>.rebase' refers to the first sentence
>> in the paragraph. Clarify by putting it in a separate paragraph.
>
> I think the patch clarifies by rewording a little, too. :)

Yes, you are right :-). Will improve it in version 3, if I'm asked to provide that.

Show 35 quoted lines
>> --- a/Documentation/git-pull.txt
>> +++ b/Documentation/git-pull.txt
>> @@ -92,12 +92,15 @@ include::merge-options.txt[]
>>  :git-pull: 1
>>
>>  --rebase::
>> -     Instead of a merge, perform a rebase after fetching.  If
>> -     there is a remote ref for the upstream branch, and this branch
>> -     was rebased since last fetched, the rebase uses that information
>> -     to avoid rebasing non-local changes. To make this the default
>> -     for branch `<name>`, set configuration `branch.<name>.rebase`
>> -     to `true`.
>> +     Instead of merging, rebase the current branch on top of the
>> +     upstream branch after fetching.  If there is a remote-tracking
>> +     branch corresponding to the upstream branch and the upstream
>> +     branch was rebased since last fetched, the rebase uses that
>> +     information to avoid rebasing non-local changes.
>> +
>> +     The default behavior is to merge rather than rebasing, but it
>> +     can be overridden per branch with the `branch.<name>.rebase`
>> +     configuration item (see git-config(1)).
>>  +
>
> Do these changes result in good output with "make -C Documentation
> git-pull.1" or "make -C Documentation git-pull.html"?  I think it
> might need to be
>
>        first paragraph
>  +
>  second paragraph
>  +
>  third paragraph
>
> or similar.
>

Oops, that's embarrassing... but thanks for the hints. I did not know that.

Junio C Hamano· Nov 10, 2010, 17:37 UTC · re: Martin von Zweigbergk · lore

Re: [PATCH v2] Documentation/git-pull: clarify configuration

Martin von Zweigbergk <martin.von.zweigbergk@gmail.com> writes:
Show 23 quoted lines
> diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
> index c50f7dc..055126e 100644
> --- a/Documentation/git-pull.txt
> +++ b/Documentation/git-pull.txt
> @@ -92,12 +92,15 @@ include::merge-options.txt[]
>  :git-pull: 1
>  
>  --rebase::
> -	Instead of a merge, perform a rebase after fetching.  If
> -	there is a remote ref for the upstream branch, and this branch
> -	was rebased since last fetched, the rebase uses that information
> -	to avoid rebasing non-local changes. To make this the default
> -	for branch `<name>`, set configuration `branch.<name>.rebase`
> -	to `true`.
> +	Instead of merging, rebase the current branch on top of the
> +	upstream branch after fetching.  If there is a remote-tracking
> +	branch corresponding to the upstream branch and the upstream
> +	branch was rebased since last fetched, the rebase uses that
> +	information to avoid rebasing non-local changes.
> +
> +	The default behavior is to merge rather than rebasing, but it
> +	can be overridden per branch with the `branch.<name>.rebase`
> +	configuration item (see git-config(1)).

The explanation looks correct in the sense that it does not say anything incorrect, and the description of non-local change exclusion in the first paragraph is more readable, I think.

But I am not sure if we want a separate paragraph here only to repeat a half of what the second paragraph in the DESCRIPTION section already said. The "default is merge" is implied by "Instead of merging" at the beginnig of this part anyway.

Also have you tried to actually format this and checked the result before submitting the patch?

Perhaps doing it like this may be better (no I didn't run AsciiDoc on it).
--rebase::
	Rebase the current branch on top of the upstream branch after
        fetching.  If there is a remote-tracking branch corresponding to
        the upstream branch and the upstream branch was rebased since last
        fetched, the rebase uses that information to avoid rebasing
        non-local changes.
+
See `branch.<name>.rebase` in linkgit:git-config[1] if you want to make
`git pull` always use `{litdd}rebase` instead of merging.
Martin von Zweigbergk· Nov 11, 2010, 01:43 UTC · re: Junio C Hamano · lore

Re: [PATCH v2] Documentation/git-pull: clarify configuration

On Wed, Nov 10, 2010 at 12:37 PM, Junio C Hamano <gitster@pobox.com> wrote:
Show 50 quoted lines
> Martin von Zweigbergk <martin.von.zweigbergk@gmail.com> writes:
>
>> diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
>> index c50f7dc..055126e 100644
>> --- a/Documentation/git-pull.txt
>> +++ b/Documentation/git-pull.txt
>> @@ -92,12 +92,15 @@ include::merge-options.txt[]
>>  :git-pull: 1
>>
>>  --rebase::
>> -     Instead of a merge, perform a rebase after fetching.  If
>> -     there is a remote ref for the upstream branch, and this branch
>> -     was rebased since last fetched, the rebase uses that information
>> -     to avoid rebasing non-local changes. To make this the default
>> -     for branch `<name>`, set configuration `branch.<name>.rebase`
>> -     to `true`.
>> +     Instead of merging, rebase the current branch on top of the
>> +     upstream branch after fetching.  If there is a remote-tracking
>> +     branch corresponding to the upstream branch and the upstream
>> +     branch was rebased since last fetched, the rebase uses that
>> +     information to avoid rebasing non-local changes.
>> +
>> +     The default behavior is to merge rather than rebasing, but it
>> +     can be overridden per branch with the `branch.<name>.rebase`
>> +     configuration item (see git-config(1)).
>
> The explanation looks correct in the sense that it does not say anything
> incorrect, and the description of non-local change exclusion in the first
> paragraph is more readable, I think.
>
> But I am not sure if we want a separate paragraph here only to repeat a
> half of what the second paragraph in the DESCRIPTION section already said.
> The "default is merge" is implied by "Instead of merging" at the beginnig
> of this part anyway.
>
> Also have you tried to actually format this and checked the result before
> submitting the patch?
>
> Perhaps doing it like this may be better (no I didn't run AsciiDoc on it).
>
>
> --rebase::
>        Rebase the current branch on top of the upstream branch after
>        fetching.  If there is a remote-tracking branch corresponding to
>        the upstream branch and the upstream branch was rebased since last
>        fetched, the rebase uses that information to avoid rebasing
>        non-local changes.
> +
> See `branch.<name>.rebase` in linkgit:git-config[1] if you want to make
> `git pull` always use `{litdd}rebase` instead of merging.

I'm happy with either your suggestion or Jonathan's. Do you want me to send an updated patch to the list or will you make the change directly?

While writing a reply to another message, I happened to spot a similar problem in the documentation for 'git rebase -s'. It currently says "Use the given merge strategy. If there is no -s option git merge-recursive is used instead. This implies --merge." and I assume the last sentence refers to the first one in this case too. Same question here: Should I send a patch?

Jonathan Nieder· Nov 11, 2010, 08:31 UTC · re: Martin von Zweigbergk · lore

Re: [PATCH v2] Documentation/git-pull: clarify configuration

Martin von Zweigbergk wrote:
Show 6 quoted lines
>                                           I happened to spot a similar
> problem in the documentation for 'git rebase -s'. It currently says "Use
> the given merge strategy. If there is no -s option git merge-recursive
> is used instead. This implies --merge." and I assume the last sentence
> refers to the first one in this case too. Same question here: Should I
> send a patch?
Yes, please!

In general, carefully written patches that improve the documentation are always welcome. (And sloppy patches are not so bad, either.)

← back to recent threads