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

"Philip Oakley" [off-list ref] writes:

From: "Junio C Hamano" <redacted>
...

quoted

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.

I think we are talking at cross purposes. My starting point is that
(the examples says that) the reader wants to create a patch series for
a local branch, relative to their <some name> branch which they
branched from...

Perhaps what you are missing is that the 'origin' in that example is
not "their" <some name> branch.  It is how we used to spell what we
call 'refs/remotes/origin/HEAD' these days, a copy of their upstream
repository's primary branch.

(e.g. the example, relative to Git, could have been from
branched from (e.g. the example, relative to Git, could have been from
a 'pu' picked up a couple of days earlier, when they'd have said 'git
format-patch pu' ;-).

Again, if that were a "'pu' picked up a few days earlier, it would
not be 'pu', but be 'origin/pu'".

quoted

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.

I was trying to avoid a literal adjustment to what I'd perceived as a
presumed workflow.

These are "examples", showing uses of commands in some hopefully
common scenarios.  I am not exactly sure what you are aiming at, but
if you are trying to strip context and/or background from them and
trying to limit them purely to "If you do X, Y happens", the
resulting description would lack clues that readers rely on in order
to choose the usage pattern of the command that is suitable for
their situation, which I do not think is a good change to make.  The
readers would be helped more with "You are in state A and want to
achieve B. If you do X starting from state A, Y happens, which helps
you achieve B.", and that is what examples are about.

Now, these "where you are and what you want to do" may not be
explicitly spelled out to avoid redundancy, and it may be an
improvement to enhance the scenario without making them too narrow.
But that would be a separate change, and renaming 'origin' (whose
modern equivalent is 'origin/master' in the context of these
examples) to 'master' alone would not do any such enhancement.

quoted

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.

So this a 'develop on master' view, rather than a 'develop on feature
branches' approach? Which could explain the misunderstanding.

The new work on the feature branches may be merged in 'master'
without ever intending to push 'master' out.  The development is
still done on the topic branches that are merged to your local
'master', perhaps for testing purposes and most likely to personally
use it before the upstream picks them up.

I suspect your misunderstanding is primarily coming from that you
may have forgotten, or you may be too new to know, that 'origin' in
the example, 'refs/heads/origin', used to be how we tracked the
primary branch of the other side back in the era when these examples
were written, and refs/remotes/origin/master is used for the same
tracking these days.