Re: [PATCH v2 1/1] doc: format-patch: don't use origin as a branch name

["Philip Oakley" <philipoakley@iee.org>]

From: "Junio C Hamano" <gitster@pobox.com>
> Philip Oakley <philipoakley@iee.org> writes:
>
>> Historically (5 Nov 2005 v0.99.9-46-g28ffb89) the git-format-patch 
>> used
>> 'origin' as the upstream branch name. That name is now used as the 
>> nominal
>> name for the upstream remote.
>>
>> While 'origin' would be DWIMmed (do what I mean) to be that remote's
>> primary branch, do not assume the reader is ready for such magic.
>
> Good thinking.
>
>> Likewise, do not use 'origin/master' which may not be up to date with 
>> the
>> remote, nor reflect the reader's master branch. The patch series 
>> should be
>> relative to the reader's view of 'git show-branch HEAD master'.
>
> This however is backwards, no?  The history on 'origin/master' may
> not be up-to-date in the sense that if you run 'git fetch' you might
> get more, but it absolutely is up-to-date in the sense that it shows
> what the origin has to the best of your repository's current
> knowledge.

I still think that the user/reader shouldn't be creating patches based 
on wherever someone else had got to, rather it should just be patches 
from their own feature branch. However the rest of your argument still 
stands with regard to accidental/unexpected conflicts with other 
upstream work, and the reader should ensure they are already up to 
date - maybe it needs a comment line to state that.

>
> Compared to that, what the user's local 'master' has is much less
> relevant.  For one thing, if a more recent commit that is on the
> remote repository is missing on 'origin/master' because you haven't
> fetched recently, by definition that commit will not be on your
> 'master' either, so you have the same staleness issue to the exact
> degree.  Even worse, when you are developing a topic to upstream, it
> is a good practice to merge your topic to your own 'master' to check
> it with the wider project codebase that is more recent than where
> your topic earlier forked from, and it makes little sense to tell
> 'exclude what I have on my master' to format-patch when extracting
> changes to upstream out of such a topic.  You send what the other
> side has, not what you do not have on your local 'master' branch.
>
>> Use the more modern 'master' as the reference branch name.
>
> There is nothing 'modern' in 'master'.

Noted.

>
> I think the original description was written before we switched to
> the separate remote layout.  What is in 'refs/remote/origin/master'
> these days was stored and updated at 'refs/heads/origin' and no
> other branch from the remote repository was tracked back then.  The
> changes to be upstreamed are output by grabbing what are not in
> 'origin', whose modern equivalent is 'origin/master'.
>
> In short, if your patch were s|origin|origin/master|, instead of
> s|origin|master|, that would be an adjustment to the more modern
> world that is still faithful to the intent of the original.

I think we would need to clarify that (the intent) for the reader. I'll 
see what I can do. (suggestion below)

>
>> Signed-off-by: Philip Oakley <philipoakley@iee.org>
>> ---
>>  Documentation/git-format-patch.txt | 10 +++++-----
>>  1 file changed, 5 insertions(+), 5 deletions(-)
>>
>> diff --git a/Documentation/git-format-patch.txt 
>> b/Documentation/git-format-patch.txt
>> index c0fd470..b0f041f 100644
>> --- a/Documentation/git-format-patch.txt
>> +++ b/Documentation/git-format-patch.txt
>> @@ -523,25 +523,25 @@ $ git format-patch -k --stdout R1..R2 | git 
>> am -3 -k
>>  ------------
>>
>>  * Extract all commits which are in the current branch but not in the
>> -origin branch:
>> +master branch:
>>  +
>>  ------------
>> -$ git format-patch origin
>> +$ git format-patch master
>>  ------------
>>  +
>>  For each commit a separate file is created in the current directory.

Perhaps insert "Note: Your 'master' should be up to date with respect to 
'origin/master' before creating and sending patches upstream to avoid 
unexpected conflicts." ?

>>
>> -* Extract all commits that lead to 'origin' since the inception of 
>> the
>> +* Extract all commits that lead to 'master' since the inception of 
>> the
>>  project:
>>  +
>>  ------------
>> -$ git format-patch --root origin
>> +$ git format-patch --root master
>>  ------------
>>
>>  * The same as the previous one:
>>  +
>>  ------------
>> -$ git format-patch -M -B origin
>> +$ git format-patch -M -B master
>>  ------------
>>  +
>>  Additionally, it detects and handles renames and complete rewrites
> --
Philip