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

From: Junio C Hamano <[email-masked]>
Date: Mon, 04 Aug 2014 09:58:44 -0700

Philip Oakley <[email-masked]> 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 <[email-masked]>
> ---
>  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