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

[Junio C Hamano <gitster@pobox.com>]

Jonathan Nieder <jrnieder@gmail.com> writes:

> Philip Oakley wrote:
>
>> Historically (5 Nov 2005 v0.99.9-46-g28ffb89) the git-format-patch used
>> 'origin' as the upstream branch name. This is now used to name the remote.
>> Use the more modern 'master' as the branch name.
>
> Would 'origin/master' make sense?

It would make a lot more sense than 'master', I think.

The 'origin' will be DWIMmed to whatever the remote designated as
its primary branch, i.e. refs/remotes/origin/HEAD, and the
assumption the examples in question makes is that the user is
following along the simplest workflow to fork from it and upstream
her changes.  Between 'origin' and 'origin/master', there isn't much
difference because of it.  In the same spirit of following the
simplest workflow, that primary branch is likely to be their
'master', so 'origin/master' is OK but longer than 'origin' [*1*].

On the other hand, 'master' names the local 'master', which may be
very stale with respect to 'origin/master', or may have tons of
unrelated things that are not in origin/master, some of which may
have come from the branch the user is running format-patch to grab
patches to upstream.  For this reason, changing 'origin' to 'master'
is not an improvement at all, I would have to say.

We could further adjust the underlying assumption to more modern
"checkout -t -b" era, and use "format-patch @{u}", but I suspect
that the readers of these examples are not yet ready for magic
before the basics to spell out things more explicitly is covered.


[Footnote]

*1* Also using 'origin' will cover the case when the primary branch
at the remote were not named 'master', so in that sense it is
slightly better and more generally applicable.