[Svnmerge] Some un-clarity in the wiki tutorial [attn: Giovanni Bajo]

[David Abrahams]

on Sun Mar 16 2008, Giovanni Bajo <rasky-AT-develer.com> wrote:

> Hi David,
>
> please feel free to CC: me on topics where you think I might have
> insights.
>
> On Sun, 2008-03-16 at 15:06 -0400, David Abrahams wrote:
>
>> * I already made one edit:
>>   http://www.orcaware.com/svn/mediawiki/index.php?title=Svnmerge.py&diff=1740&oldid=1709,
>>   but I'm afraid
>> 
>>     "if you're currently in a working copy directory containing trunk:
>>     svn copy trunk branch; cd branch"
>> 
>>   is still a bit too esoteric because people rarely are sitting in a WC
>>   directory that *contains* the trunk directory.  Typically, they've done
>> 
>>      svn co url://of/the/trunk projectname
>> 
>>   and the best way to get to the state described is something like:
>> 
>>      svn cp url://of/the/trunk url://of/the/branch
>>      svn switch url://of/the/branch
>> 
>>   Isn't that right?
>
> Yes, it is right. I've adjusted the text to clarify it. I think that
> speaking of how to create a branch in a tutorial that "assumes that you
> are working on a recently-created development" can only be confusing, so
> I just left the switch hint.

Great, thanks.  Hmm, maybe now we need to define "pristine."  I _think_
what it means is "a branch whose BASE" has never had any changes merged
into it from the trunk.  Right?

>> * I'm really surprised to see
>> 
>>     "svnmerge.py is meant to always operate in this condition (so let me
>>     repeat: top-level directory, no local modifications"
>> 
>>   given that http://kenkinder.com/svnmerge/ says
>> 
>>     "You can tell svnmerge about the branches after the fact, but if you
>>     do it up front, you won't need to tell it from what revision numbers
>>     the branches came."
>> 
>
> What this old and possibly outdated tutorial is trying to say is that
> it's better to run "svnmerge.py init" immediately after branch creation,
> before doing any work on it.

Yeah, I understand it's saying that... but why?

> Otherwise, you're probably better off putting an explicit revision range
> telling it which parts of the branch's head (eg: trunk) has been already
> merged. 

"Merged" into the branch, IIUC.

> See also below about this.

But if nothing has been merged into the branch from the trunk, IIUC,
svnmerge figures it out without help?

>>   and, having some rough idea about what "svnmerge.py init" is supposed
>>   to do, 
>
> It basically tries to find out two things:
>
> 1) the URL of the branch's head (eg: trunk).
> 2) the revision number at which the branch has been generated off its
> head. 

All of which is entirely independent of local modifications, right?

> This is important because svnmerge.py shouldn't care about any revision
> *before* that one, but only revisions after that one (that is, changes
> happened in the head after the branch was created, and that potentially
> need to be merged into the branch).
>
> But what if there are revisions in the branch after the branchpoint:
> there are two possibilities here:
>
>  * Those revisions are normal branch commits, so svnmerge.py shouldn't
> worry.
>  * Those revisions are manual merges done without svnmerge.py, and thus
> you need to teach svnmerge.py about those merges (= you need to tell it
> what commits in the head are already been merged into the branch), so
> that it won't try to merge those twice.

Right.  Again, local modifications don't matter.

> So, in most cases, if you run "svnmerge.py init" without any further
> option, and immediately after branch creation, it will be able to find
> out #1 (URL) and #2 (branchpoint) automatically without any problem. 
>
> Otherwise, if you're adding svnmerge.py to a branch that went along
> without svnmerge.py for a while, and was manually merged, you can
> either:
>
>  * Run "svnmerge.py init" to initialize it off the branchpoint, and then
> teach it about merges that already happened through "svnmerge.py
> integrated" (best suit for release branches because of their cherry-pick
> nature).
>  * Run "svnmerge.py init HEAD_URL --revision=REVLIST" to initialize it
> and teach about the merged revisions in one show. This is best suit for
> development branches, where the REVLIST is probably something like
> 1-NNN, where "NNN" is the last head mergepoint (the last revision of the
> head that was merged into the branch).

This is all good stuff that probably should be added to the tutorial.
Better to leave people with a more complete understanding than a
prescription and false fears.

>>   it seems to me that it shouldn't care about the local state of
>>   the working copy.  Is it really correct that you can't have local
>>   modifications?
>
> No, snvmerge.py doesn't specifically care about the working copy status;
> the fact that it checks for local modifications and abort if there are
> any, is just to save you from operational mistakes (where you have some
> local modification that gets accidentally committed within a merge). 

I'm still not seeing what this saves you from in the case of
"svnmerge.py init."  Maybe the check should be disabled in that case.


-- 
Dave Abrahams
Boost Consulting
http://boost-consulting.com