Correct (best-practise?) procedure to stay in sync with a remote Mercurial repository?

Question

As a former user of Subversion, we've decide to move over to Mercurial for SCM and it is confusing us a little. Although Mercurial is a distributed SCM tool we are using a remote repo to keep changes we make backed up on a server but we are finding a few teething troubles.

For example, when two or three of us work on our local repo's, we commit then push to the remote repo, we find that a lot of heads(?) are created. This confused the hell out of us and we had to do some merging etc to sort it out.

What is the best way to avoid so many heads and to keep a remote repo in sync with a number of developers?

Today, i've been working like this:

1. Change a File.
2. Pull from remote repo.
3. Update local working copy.
4. Merge? (why?)
5. Commit my changes to local repo.
6. Push to the remote repo.

Is this the best proceedure?

Although this has worked fine today, i can't help that feeling that i'm doing it wrong! To be honest i don't understand why merging even needs to be done at the pull stage because other people are working on different files?

Other than to tell me to RTFM have you any tips for using Mercurial is such a way? Any good online resources for information on why we get so many heads?

NOTE: I have read the manual but it doesn't really give much detail and i don't think i want to start another book at the minute.

Answer 1

You should definitely find some learning resources.

I can recommend the following:

• hginit.com
• Tekpub: Mercurial

As for your concrete question, "is this the best procedure", then I would have to say no.

Here's some tips.

First of all, you don't need to stay "in sync" with the central repository at all times. Instead, follow these guidelines:

• Push from your local repository to the central one when you're happy with the changes you've committed. Remember, this can be several changesets
• Pull if you need changes others have done right away, ie. there's a bugfix a colleague of yours has fixed, that you need, in order to continue with your own work.
• Pull before push
• Merge any extra heads you pulled down with your own changes, before you push, or continue working

In other words, here's a typical day.

You pull the latest changes when you come in in the morning, so that you got an up to date local clone. You might not always do this, if you're in the middle of bigger changes that you didn't finish yesterday.

Then you start working. You commit small changesets with isolated changes That isn't to say that you split up a larger bugfix into many smaller commits just because you modify multiple files, but try to avoid fixing more than one bug at a time, or implementing more than one feature at a time. Try to stay focused.

Then, when you're happy with all the changesets you've added locally, you decide to push to the server. When you try to do this, you get an abort message saying that extra heads would be pushed to the server, and this isn't allowed, so the push is aborted.

Instead you pull. This can always be done, but will of course now add extra heads in your local clone, instead of at the server.

Then you merge, the extra head that you got from the server, with your own head, the one that you created during the day by committing new changesets to your clone. You resolve any merge conflicts.

Then you push, and now it should succeed. On the off chance that someone has managed to push more changesets to the central repository while you were busy merging, you will get another abort and have to rinse and repeat.

The history will now show multiple parallel branches of development, but should always stay at max 1 head in your central repository. If, later on, you start using named branches, you can have 1 head per named branch, but try to avoid this until you get the hang of just the default branch.

As for why you need to merge? Well, Mercurial always work with revisions that are snapshots of the entire project, which means two branches, even though they contain changes to different files, are really considered two different versions of the entire project, and you need to tell Mercurial that it should combine them to get back to one version.

Answer 2

For one, you can pull at any time; pulling does just add changesets to your repo, but not change your local working files (except if you have enabed the post-pull update).

Merging is necessary if someone else has commited changes to the same branch you're currently working on. This created an implicit branch, and merging merely brings them back together. You can see this nicely with the "railroad track" in the repository view. Basically, as long as you don't merge, you stay on your own "private" track, and when you want to add your changes (can be any amount of changesets) you merge it back into the destination branch (typically "default"). It's painless - nothing like merging in older SVN versions!

So the workflow is not as rigid as you displayed it; it's more like this:

• Pull as much as you like
• Make changes and commit locally as often as you like
• When your changes should be integrated, merge with the destination branch (can be a lower revision than the newest), commit and push

This workflow can be tuned somewhat, for instance by using named branches and sometimes by using rebase. However, you and your team should decide on the workflow to be used; Mercurial is quite flexible in this regard.

Answer 3

http://hginit.com has a good tutorial.

In particular, you'll find the list of steps you have here: http://hginit.com/02.html (at the bottom of the page)

The difference between those steps and yours is that you should commit after step 1. In fact you will typically commit several times on your local repository before moving onto the pull/merge/push step. You don't need to share every commit with the rest of developers right away. It'll often make sense to do several related changes and then push that whole thing.