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

resending - send mail failure
----- Original Message ----- 
From: "Philip Oakley" <redacted>
To: "Junio C Hamano" <redacted>
Cc: "GitList" <redacted>; "Jonathan Nieder" 
[off-list ref]
Sent: Wednesday, August 13, 2014 5:03 PM
Subject: Re: [PATCH v2 1/1] doc: format-patch: don't use origin as a 
branch name

From: "Junio C Hamano" <redacted>
Sent: Tuesday, August 05, 2014 7:19 PM

quoted

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

quoted

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.

Aha, I had a revelation as to where you were coming from in terms of 
workflow and now see what you were meaning, and how it differed from 
my perception of the workflow.

I've documented the different expectations at the end (for those 
interested),
however of more interest is how the confusion happened and what can be
learned from it. We should be ensuring that the examples avoid any 
such
confusion. It can't be assumed that readers appreciate the history of 
Git so the starting example should be both simple relative to the 
synopsis and give the any necessary background workflow info.

quoted

quoted

(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'".

We haven't been clear how the branch is 'picked up' which, to me, is
partly where the expectation diverged.

The other aspect (to me, a more recent learner of git) is that
established users were already used to the integrated nature of the
remote's DAG, while it's a mental extra step for newer users to link
across the 'refs/remotes/<name>/<branch>' divide, when a lot of advice
is of the type 'don't work on/with remote branches - there be 
dragons'.

quoted

quoted

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.

At the moment the example already lacked sufficient context.

quoted

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

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

I'll look to update the patch for review in the next week or so, 
though family/work commitments may delay further.

Philip

Ascii art of the workflows
Example: Documented
===================

Build on top workflow; With fetch, not pull, update

The user is working on top of his 'master' branch.

       / -              origin/master
       ¦
A - B - C - x - y - z    (local) master  [built upon origin/master]
        \
         \
           D - E - G
                   ^    (refreshed/fetched from upstream) 
origin/master

In both cases (with or without a refresh/fetch from upstream), 'git
format-patch origin/master' will find commit 'C' as the branch point
(aka merge-base), and will create patches for commits x, y, and z.

This is the workflow I think Junio is using as his basis for 
discussion.
(This fits well with the historic methods of working with remotes, 
which
were not as explicit differentiated as they are now)

With this simple [easy] view of that worflow then:
At some point, when the patchs have been accepted upstream, one must
drop one's current (local) master branch and 'git reset --hard
origin/master' to become up to date with the upstream.

--

My viewpoint, based on my development on 'pu' style coding would start
with this view of the described flow. (Here the starting point is that
remotes are viewed as 'separate' from local branches.)

       / -              origin/master when development started,
       ¦                    ref no longer valid.
       ¦
A - B - C - x - y - z    (local) master  [built upon origin/master]
\
 \
   B'- C'- D - E - G    (fetched) upstream has rewound/rebased
                   ¦              (as per some published policy)
                   ¦
                   ^    (refreshed) origin/master

Note that here the 'git format-patch origin/master' will find commit 
'A'
as the branch point (aka merge-base), and produce additional patches 
for
commits B and C as well as the desired x, y & z. Hence my initial 
replies.


In fact my workflow doesn't develop 'on-top', rather uses the 'feature
branch' viewpoint, so:


       / -              origin/master when development started,
       ¦                  ref no longer valid.
       ¦
A - B - C                (local) master
¦       ¦                 [starts at original origin/master]
¦        \
¦         \ x - y - z    (feature branch) 'current'
\
 \
   B'- C'- D - E - G    upstream has rewound/rebased
                   ¦     (e.g. as per published policy *note*)
                   ¦
                   ^    (refreshed) origin/master

Here the command 'git format-patch origin/master' would be wrong (as
above), while 'git format-patch master' would be the desired user 
action
(patches just for x, y & z).

*note*: while rewinding 'master' is untypical (if not insane), it can 
be normal for some published branches, e.g. Git's pu branch.