mozilla

Revision 52520 of Mercurial basics

  • Revision slug: Mercurial_basics
  • Revision title: Mercurial basics
  • Revision id: 52520
  • Created:
  • Creator: Jorend
  • Is current revision? No
  • Comment

Revision Content

I am about to tell you some stuff about Mercurial that will save you a lot of frustration. —jorendorff 16:06, 12 May 2008 (PDT)

Expectations

Mercurial is not CVS. The commands aren't the same. The concepts aren't the same.

Mercurial is not magic dust. See, here's the problem. 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. (We've tried lots of stuff. For example, we tried sharing patch queues. It turned out to be kinda unpleasant and error-prone. Not everything works out.)

This gun is loaded. You can shoot yourself in the foot. You can lose work. The tool tries to protect you from this, but it can happen anyway. The usual failure mode is, you do something especially hg commit, hg update, or hg qrefresh, either (a) without knowing what it's going to do, or (b) with a mistaken understanding of the state of your repository or working directory. 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.

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


Avoiding trouble

Use Mercurial 1.0 or later. (hg version to check.)

Don't run a command unless you know what it's going to do. It sounds dumb, but I've lost work with Mercurial several times by breaking this rule.

Don't use -f. Just don't.

Learn how to get your bearings. Use read-only commands (like hg status, hg head, hg parents, hg log, hg diff) to check the status of your repository. This is a key skill.

Configure a merge program. DO IT NOW. The #1 cause of frustration. You know how CVS leaves conflict markers in your files sometimes? Mercurial, by contrast, 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, citing inexplicable hg behavior, literally abandoning work because of a bad merge.

So yeah, configure a merge program and make sure you know how to use it. Please.

If you use Mercurial Queues, back up your work. 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.


Recovering

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.

Ask for help on IRC. Try #developers on Mozilla IRC or #mercurial on FreeNode.

Revision Source

<p>I am about to tell you some stuff about <a href="en/Mercurial">Mercurial</a> that will save you a lot of frustration.  —<a href="User:Jorend">jorendorff</a> 16:06, 12 May 2008 (PDT)
</p>
<h3 name="Expectations"> Expectations </h3>
<p><b>Mercurial is not CVS.</b>  The commands aren't the same.  The concepts aren't the same.
</p><p><b>Mercurial is not magic dust.</b>  See, here's the problem.  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.  (We've tried lots of stuff.  For example, we tried sharing patch queues.  It turned out to be kinda unpleasant and error-prone.  Not everything works out.)
</p><p><b>This gun is loaded.</b>  You can shoot yourself in the foot.  You can lose work.  The tool tries to protect you from this, but it can happen anyway.  The usual failure mode is, you do something especially <code>hg commit</code>, <code>hg update</code>, or <code>hg qrefresh</code>, either (a) without knowing what it's going to do, or (b) with a mistaken understanding of the state of your repository or working directory.  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.
</p><p>Also, 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.
</p><p><br>
</p>
<h3 name="Avoiding_trouble"> Avoiding trouble </h3>
<p><b>Use Mercurial 1.0 or later.</b>  (<code>hg version</code> to check.)
</p><p><b>Don't run a command unless you know what it's going to do.</b>  It sounds dumb, but I've lost work with Mercurial several times by breaking this rule.
</p><p><b>Don't use <code>-f</code>.</b>  Just don't.
</p><p><b>Learn how to get your bearings.</b>  Use read-only commands (like <code>hg status</code>, <code>hg head</code>, <code>hg parents</code>, <code>hg log</code>, <code>hg diff</code>) to check the status of your repository.  This is a key skill.
</p><p><b>Configure a <a class="external" href="http://www.selenic.com/mercurial/wiki/index.cgi/MergeProgram">merge program</a>.  DO IT NOW.</b>  The #1 cause of frustration.  You know how CVS leaves conflict markers in your files sometimes?  Mercurial, by contrast, wants you to fix the conflicts <i>right now</i>, using a merge program (like <code>kdiff3</code>) which it launches for you.
</p><p>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, citing inexplicable hg behavior, literally abandoning work because of a bad merge.
</p><p>So yeah, <a class="external" href="http://www.selenic.com/mercurial/wiki/index.cgi/MergeProgram">configure a merge program</a> and make sure you know how to use it.  Please.
</p><p><b>If you use Mercurial Queues, back up your work.</b>  Use <code>hg qinit -c</code> to create a separate backup repository for your patches and <code>hg qcommit -m backup</code> regularly.
</p><p><b>Don't use Mercurial Queues in a repository that someone might pull from.</b>
</p><p><br>
</p>
<h3 name="Recovering"> Recovering </h3>
<p>Oops!  Mercurial cut off your arm!
</p><p><b>Don't randomly try stuff to see if it'll magically fix it.</b>  Remember what you stand to lose, and <i>set down the chainsaw</i> while you still have one good arm.
</p><p><b>Ask for help on IRC.</b>  Try <a class="external" href="irc://irc.mozilla.org/developers">#developers on Mozilla IRC</a> or <a class="external" href="irc://irc.freenode.net/mercurial">#mercurial on FreeNode</a>.
</p>
Revert to this revision