I am about to tell you some stuff about Mercurial that will save you a lot of frustration. This page is cynical and survival-oriented. But I still claim Mercurial is a lot better than CVS. —jorendorff 16:06, 12 May 2008 (PDT)
Mercurial is not CVS. The commands aren't the same. The concepts aren't the same.
This gun is loaded. You can shoot yourself in the foot. You can lose work. The tool tries to protect you, but it can happen anyway. The two common failure modes are: (a) you run a command without knowing what it's going to do; (b) you
hg commit or
hg qrefresh with a mistaken understanding of the state of your working directory. So you accidentally commit changes that you didn't want to commit; or you accidentally commit a broken merge; etc. Often it's not immediately obvious that anything is wrong.
Forewarned is forearmed. Don't do these things. Don't run commands without knowing what they're going to do. Don't commit without diffing and thinking. And don't let yourself get into "play mode" and stop paying attention to the fact that what you're playing with is your own uncommitted work.
Mercurial is not magic dust. Mercurial is flexible, powerful, and fun. It lets you attempt stuff you never would have tried in CVS. But of course not everything turns out to have been a good idea. (For example, we tried sharing patch queues. It sort of sucked.)
Use Mercurial 1.0 or later. (
hg version to check.)
Learn how to get your bearings. Use read-only commands (like
hg diff) to check the status of your repository. This is a key skill.
Configure a merge program and make sure you know how to use it. DO IT NOW. Otherwise you will likely screw up your repository at some point.
CVS leaves conflict markers in your files sometimes. Mercurial doesn't: instead, it wants you to fix the conflicts right now, using a merge program (like
kdiff3) which it launches for you.
This can be error-prone. By default, Mercurial uses the first merge program it finds on your system, and most merge programs are kinda hard to use correctly. Mercurial does not do a good job of detecting busted merges and refusing to proceed, so just by closing a window you can unwittingly put yourself in a bad state. Grown men have been known to walk away from whole hg trees containing many hours' worth of work, citing inexplicable hg behavior, because of a bad merge.
If a merge fails, make sure Mercurial knows that it has failed. When you're first learning the ropes, merges often go wrong. You might see this message:
0 files updated, 0 files merged, 0 files removed, 1 files unresolved There are unresolved merges, you can redo the full merge using: hg update -C 2 hg merge 1
This means something went wrong. If you don't know exactly what it is and how to fix it, use that
hg update -C command to tell Mercurial that you've given up on that merge.
If you don't, Mercurial won't know, and the next time you commit, it'll make a merge changeset. This is bad. The result can look a lot like accidentally destroying a bunch of work, actually, but the damage can be undone.
hg parents shows two parents, you're merging.
If you use Mercurial Queues, back up your work.
hg qrefresh destructively replaces the old patch with the new one! Use
hg qinit -c to create a separate backup repository for your patches and
hg qcommit -m backup regularly.
Don't use Mercurial Queues in a repository that someone might pull from.
Oops! Mercurial cut off your arm!
Don't randomly try stuff to see if it'll magically fix it. Remember what you stand to lose, and set down the chainsaw while you still have one good arm.