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

> 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.

>
> 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'.

>
> 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.

>
>> 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.

>>
>> -* 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
> --