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

From: Junio C Hamano <gitster@pobox.com>
Date: Aug 1, 2014, 20:08 UTC
Message-ID: <xmqq8un8ug5d.fsf@gitster.dls.corp.google.com>
In-Reply-To: <20140801193614.GR12427@google.com>

Jonathan Nieder <jrnieder@gmail.com> writes:

Show 7 quoted lines

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