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 15:12:13 -0700

"Philip Oakley" <[email-masked]> writes:

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

You forked your topic branch off of the shared project history aka
origin/master and built some.  You may have sent some patches off of
your previous work to the upstream, and origin/master may or may not
have applied some of them since your topic forked from it.  The
patches you are sending out is from your own topic branch.

You may be cooking multiple topics, and your local 'master' branch,
which you never push back to 'origin/master', may contain any of
these branches.  You do not fork off a new topic out of there.  Best
case, you would fork from 'origin/master'; a bit worse case, you
have to fork from another of your topic branch that your new topic
has to depend on.

Nowhere I am assuming that "the reader is creating paches based on
wherever someone else had got to".  Sorry, but I have no idea what
you are complaining about.

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

Sorry, but I am not sure how much you understood what I wrote.

The primary reason why 'origin' in the example should be replaced
with 'origin/master' is because that is the literal adjustment from
the pre-separate-remote world order to today's world order.  The
local branch 'origin' (more specifically, 'refs/heads/origin') used
to be what we used to keep track of 'master' of the upstream, which
we use 'refs/remotes/origin/master' these days.

	Side note: DWIMming origin to remotes/origin/HEAD to
	remotes/origin/master was invented to keep supporting this
	"'origin' keeps track of the default upstream" convention
	when we transitioned from the old world order to
	separate-remote layout.

And the reason why 'origin' should not be replaced with 'master' is
because your 'master' may already have patches from the topic you
are working on, i.e. in your current branch, that the upstream does
not yet have.  Running "git format-patch origin/master" will show
what needs to be accepted by the upstream from you to reproduce your
work in full; if you run "git format-patch master", it may miss some
parts that you already have in your local 'master' but not yet in
the upstream.

I never talked about conflicts, and I still think that it is
completely outside the scope of these examples.  Avoidance of
conflicts with the work that is already commited to your upstream
since you forked is the job for "rebase", not "format-patch".  The
reason why it is wrong to replace 'origin' in that text with 'master'
does not have anything to do with conflict avoidance.

Puzzled...