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

[Giovanni Bajo]

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.

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

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. See also below about this.

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

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.

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

>   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). If
you think of it, you don't want to run merges with pending modifications
in your working copy.

But if you know what you are doing, just use --force and svnmerge.py
will happily run from a dirty working copy.
-- 
Giovanni Bajo
Develer S.r.l.
http://www.develer.com