Re: [glob2-devel] Mercurial, Branching and Merging

[Kai Antweiler]

> I've read up on Mercurial, and for the most part I understand the
> system. I know that we have a master copy hosted at
> https://hg.globulation2.org/glob2/. But what about branches? Mercurial
> seems to imply that every clone of a respitory is a branch, and in
> Glob2, we will just merge those branches back into the master.

Yes that is the traditional mercurial way of branches.
But as Steph wrote there is a new (introduced last year) option for
branches, that isn't as well documented as the rest.


> But what about shared branches? If we wanted to do a shared branch,
> someone would have to host that respitory in the same way that we host
> the current master here? And does this not imply that the admin has to
> be available whenever we want to do a shared branch? Or am I missing
> something?

Yes that are some problems of the traditional mercurial branches.
Those branches are better but the cvs-style branches are more convenient
for us.


Basically you have to know that there is not total order on a mercurial
repository.  Each revision exept the initial revision has at least one
parent.  And different revisions can have the same parent(s).
A revision will have more than one parent, if and only if
it is a merge of those parents.

If two or more revisions share a parent, we have infact different
branches in the repository.  The new mercurial feature allows to
give a revision a sticky tag that is past to almost all its children.
Exeptions are merges.  If you merge branch A into branch B, this
revision will belong to branch B.  So when you merge the master branch
into a development branch, the result will belong to the development
branch.  This is good because you can keep track of approved changes,
during your development now and then.

Branches don't have names, unless you give them a name.
I don't know whether the names have to be unique.
So multiple branches were supported all the time.  The new feature
just allows to name them.
You can put the branchname everywhere you can put a revision number.
So all commands that have '-r' or '-rev' option accept a branchname too.
Mercurial will then search the latest revision in that branch and path
its number to the command.  (At least that's what I think it does.)

If every branch (named or not) has the same "latest revision",
our repository will have exactly 1 head.
Otherwise we will have more heads and mercurial will suppose that
we merge the heads.  But most of the time this would be inappropriate,
and we shouldn't do it.

The latest revision is always called tip, and mercurial defaults
to think that we want to work on it.  This is also very sad, if
it does belong to an other branch.
I really recomment that you only pull the branch you want to use.
You can do this, because the clone and pull commands have a '-r'
option.  I pull the whole repository on my computer and than
pull the branches that I want to work on, from that local repository
to different working repositories.  I suggest everyone should do this.
So there is one incoming repository, one or more working repository
and one outgoing repository locally on my computer.

Our master branch I called "master".  But the first twothousendsomething
revisions of that branch have no name.

Glob2 players should always pull the master branch.
Unfortunately we can't force them.

You can try everything mercurial locally before pushing to the
remote repository.
"hg log", "hg diff", "hg branch", "hg heads", "hg incoming", "hg outgoing"
and "hg status" are very helpfull.
Oh, and "hg help" and "hg help <command>" too.

Please look into the extentions.
"hg view" is very good for an graphical overview of the repository
structure, though it seems not to display the branch names.
And you definetly have to set up a merge tool for those case when
you have to merge manually.


Back to the topic:
Branching of should look like this:

In case you don't want to branch from the tip of your local repository:
"hg revert --all -r <revision from which you want to branch of>"

"hg branch <branchname>"
"hg commit"

done.

Cloning from a branch:
"hg clone -r <branchname> <location of the repository> <name that you
want your  repository to have>"

Pulling from a branch:
"hg pull -r <branchname> <location of the repository>"

--
Kai Antweiler