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

["Philip Oakley" <philipoakley@iee.org>]

resending - send mail failure
----- Original Message ----- 
From: "Philip Oakley" <philipoakley@iee.org>
To: "Junio C Hamano" <gitster@pobox.com>
Cc: "GitList" <git@vger.kernel.org>; "Jonathan Nieder" 
<jrnieder@gmail.com>
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" <gitster@pobox.com>
> Sent: Tuesday, August 05, 2014 7:19 PM
>> "Philip Oakley" <philipoakley@iee.org> writes:
>>
>>> From: "Junio C Hamano" <gitster@pobox.com>
>>> ...
>>>> 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.
>
>>
>>> (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'.
>
>>
>>>> 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.
>>
>> 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.
>>
>>>> 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.