Mercurial

  • Revision slug: Mercurial
  • Revision title: Mercurial
  • Revision id: 67693
  • Created:
  • Creator: Dmandelin
  • Is current revision? No
  • Comment added note about cvs-trunk-mirror

Revision Content

Mercurial is the distributed version control software we're using for {{mediawiki.interwiki('wikimo', 'Mozilla_2', 'Mozilla 2')}} development. It will eventually replace CVS.

hg is the Mercurial command-line tool, Hg being the chemical symbol for the element mercury.

How Mercurial is different

Mercurial vs. CVS:

  • Mercurial checkins are atomic.
  • In Mercurial, tagging is fast and O(1).
  • Mercurial makes it easy for anyone to fork the central repository. (The command is hg clone.)
  • With Mercurial, a complete, fully armed and operational clone of the entire Mozilla repository is on your local hard drive. You can do work locally and check it in without affecting anybody else. To push changes upstream, use hg push.
  • Mercurial queues can help you juggle patches. It's like Quilt. The idea behind Quilt is this:

    The scripts allow to manage a series of patches by keeping track of the changes each patch makes. Patches can be applied, un-applied, refreshed, etc.

    The key philosophical concept is that your primary output is patches. Not ".c" files, not ".h" files. But patches. So patches are the first-class object here.

  • When CVS finds merge conflicts, it puts conflict markers in your file. When Mercurial finds merge conflicts, it launches a merge program. This is a pain in the neck.
  • In a lot of places where CVS is per-file or per-directory, Mercurial is per-repository. For example, a single Mercurial changeset may contain changes to many files throughout the tree.
  • We hope Mercurial will allow us to rethink the way we work. Teams and individuals should be able to branch and merge much more easily—without opening IT tickets. People outside the community who are powerhouse developers should be able to do surprising stuff with this. Companies maintaining forks of Mozilla should have an easier time too. It all sort of remains to be seen, though.

Basics

Installing Mercurial

If you use apt-get, emerge, port, or yum to install software, just do the usual. If not, the Mercurial binary packages are for you. Or see {{mediawiki.interwiki('wikimo', 'Mercurial_on_Windows', 'wikimo:Mercurial on Windows')}}.

After installing, choose a merge program. Seriously. Do it now. If you don't, Mercurial will choose one for you and spring it on you when you least expect it.

The Windows version of Mercurial does not automatically convert line endings between Windows and Unix styles. All our repositories use Unix line endings. We need a story for Windows, but right now I have no ideas.

Checking out

The Mozilla 2 trunk is located at http://hg.mozilla.org/mozilla-central .

You need Python 2.4 or later just to check everything out. This is because we're using Python to do some checkout-related stuff that client.mk used to do—blame bsmedberg ;)

hg clone http://hg.mozilla.org/mozilla-central
cd mozilla-central
python client.py checkout    # <--- *** don't forget this ***

After that you can just get yourself a .mozconfig file and build as you normally would.

If you get the error message "No module named subprocess", that's because you didn't install Python 2.4 or later. Go back two paragraphs.

{{template.Warning("If you don\'t run client.py, it won\'t build. Then you\'ll go on IRC and ask why it won\'t build, and once it becomes clear that you haven\'t run client.py, you will be ruthlessly mocked. (This is maybe not the best failure mode, but that\'s how it works right now. Sorry!)")}}

For an up-to-date copy of CVS trunk via hg (rather than the Mozilla 2 trunk), see http://hg.mozilla.org/cvs-trunk-mirror. In order to build, you'll need to run the same client.py script, which is not provided in cvs-trunk-mirror, you need to get that from mozilla-central, then copy it into the source directory and run.

Editing and updating

You can randomly edit files, just like CVS.

The equivalent of cvs up is:

hg pull -u

Diffing and patching

  • hg diff diffs the entire tree by default. Use hg diff . (note the dot) to diff only the current directory.
  • When applying a patch generated by Mercurial, use patch -p1, not patch -p0. (This is due to a quirk of Mercurial diff output—it refers to fictional "a" and "b" directories. Don't ask.)

hg has no exact equivalent of cvs diff -u8p. The simplest thing is hg diff, which provides 3 lines of context.

To get 8 lines of context, enable the hg extdiff command (by editing your ~/.hgrc file). If you agree this is super lame, please leave a polite comment at http://www.selenic.com/mercurial/bts/issue654 .

Checking in

To commit your changes to your local repository:

hg commit

To push those changes upstream to the central repository:

hg push

For that to work, you have to have committer access, and you must edit the file (your-local-hg-root)/.hg/hgrc to add this line:

[paths]
default = http://hg.mozilla.org/mozilla-central/
default-push = ssh://hg.mozilla.org/mozilla-central/

You'll get a bogus error message each time you push:

remote: Could not chdir to home directory : No such file or directory

Just ignore it.

What we don't have

There's no Bonsai for mozilla-central; but if you go to http://hg.mozilla.org/mozilla-central/ and click on "manifest", you can at least browse the tree and get "revisions" (change logs) or "annotate" (blame) for files. (And it works for any repository, not just mozilla-central.)

There's no LXR/MXR for mozilla-central.

There's no Bugzilla integration for Mercurial.

See also

The hg book is the definitive Mercurial user guide.

Category:Mercurial lists the Mercurial-related articles on MDC.

And on wiki.mozilla.org, these helpful pages:

  • {{mediawiki.interwiki('wikimo', 'Using_Mercurial_locally_with_CVS', 'Using Mercurial locally with CVS')}}, a how-to.
  • {{mediawiki.interwiki('wikimo', 'Mercurial_on_Windows', 'Mercurial on Windows')}}

Revision Source

<p><b>Mercurial</b> is the <a class="external" href="http://blog.ianbicking.org/distributed-vs-centralized-scm.html">distributed version control software</a> we're using for {{mediawiki.interwiki('wikimo', 'Mozilla_2', 'Mozilla 2')}} development.  It will eventually replace CVS.
</p><p><b><code>hg</code></b> is the Mercurial command-line tool, Hg being the chemical symbol for the element mercury.
</p>
<h2 name="How_Mercurial_is_different"> How Mercurial is different </h2>
<p>Mercurial vs. CVS:
</p>
<ul><li> Mercurial checkins are atomic.
</li></ul>
<ul><li> In Mercurial, tagging is fast and O(1).
</li></ul>
<ul><li> Mercurial makes it easy for anyone to fork the central repository.  (The command is <code>hg clone</code>.)
</li></ul>
<ul><li> Mercurial makes branching quick and easy and keeps merging pretty much sane.  (See <a href="en/Publishing_Mercurial_Clones">Publishing Mercurial Clones</a>.)
</li></ul>
<ul><li> With Mercurial, a complete, fully armed and operational <i>clone</i> of the entire Mozilla repository is on your local hard drive.  You can do work locally and check it in without affecting anybody else.  To push changes upstream, use <code>hg push</code>.
</li></ul>
<ul><li> <a class="external" href="http://hgbook.red-bean.com/hgbookch12.html#x16-26700012">Mercurial queues</a> can help you juggle patches.  It's like <a class="external" href="http://savannah.nongnu.org/projects/quilt">Quilt</a>.  The idea behind Quilt is this:  <blockquote><p>The scripts allow to manage a series of patches by keeping track of the changes each patch makes. Patches can be applied, un-applied, refreshed, etc.</p> <p>The key philosophical concept is that your primary output is patches. Not ".c" files, not ".h" files. But patches. So patches are the first-class object here.</p> </blockquote>
</li></ul>
<ul><li> When CVS finds merge conflicts, it puts conflict markers in your file.  When Mercurial finds merge conflicts, it launches a <a class="external" href="http://www.selenic.com/mercurial/wiki/index.cgi/MergeProgram">merge program</a>.  This is a pain in the neck.
</li></ul>
<ul><li> In a lot of places where CVS is per-file or per-directory, Mercurial is per-repository.  For example, a single Mercurial changeset may contain changes to many files throughout the tree.
</li></ul>
<ul><li> <b>We hope Mercurial will allow us to rethink the way we work.</b>  Teams and individuals should be able to branch and merge much more easily—without opening IT tickets.  People outside the community who are powerhouse developers should be able to do surprising stuff with this.  Companies maintaining forks of Mozilla should have an easier time too.  It all sort of remains to be seen, though.
</li></ul>
<h2 name="Basics"> Basics </h2>
<h3 name="Installing_Mercurial"> Installing Mercurial </h3>
<p>If you use <code>apt-get</code>, <code>emerge</code>, <code>port</code>, or <code>yum</code> to install software, just do the usual.  If not, the <a class="external" href="http://www.selenic.com/mercurial/wiki/index.cgi/BinaryPackages">Mercurial binary packages</a> are for you.  Or see {{mediawiki.interwiki('wikimo', 'Mercurial_on_Windows', 'wikimo:Mercurial on Windows')}}.
</p><p>After installing, <b>choose a <a class="external" href="http://www.selenic.com/mercurial/wiki/index.cgi/MergeProgram">merge program</a></b>.  Seriously.  Do it now.  If you don't, Mercurial will choose one for you and spring it on you when you least expect it.
</p><p>The Windows version of Mercurial does not automatically convert line endings between Windows and Unix styles.  All our repositories use Unix line endings.  We need a story for Windows, but right now I have no ideas.
</p>
<h3 name="Checking_out"> Checking out </h3>
<p>The Mozilla 2 trunk is located at http://hg.mozilla.org/mozilla-central .
</p><p>You need <a class="external" href="http://www.python.org/download/">Python 2.4 or later</a> just to check everything out.  This is because we're using Python to do some checkout-related stuff that <code>client.mk</code> used to do—blame bsmedberg ;)
</p>
<pre class="eval">hg clone <span class="plain">http://hg.mozilla.org/mozilla-central</span>
cd mozilla-central
python client.py checkout    # &lt;--- *** don't forget this ***
</pre>
<p>After that you can just get yourself a .mozconfig file and build as you normally would.
</p><p>If you get the error message "No module named subprocess", that's because you didn't install Python 2.4 or later.  Go back two paragraphs.
</p><p>{{template.Warning("If you don\'t run client.py, it won\'t build.  Then you\'ll go on IRC and ask why it won\'t build, and once it becomes clear that you haven\'t run client.py, you will be ruthlessly mocked.  (This is maybe not the best failure mode, but that\'s how it works right now.  Sorry!)")}}
</p><p>For an up-to-date copy of CVS trunk via hg (rather than the Mozilla 2 trunk), see http://hg.mozilla.org/cvs-trunk-mirror. In order to build, you'll need to run the same client.py script, which is not provided in cvs-trunk-mirror, you need to get that from mozilla-central, then copy it into the source directory and run.
</p>
<h3 name="Editing_and_updating"> Editing and updating </h3>
<p>You can randomly edit files, just like CVS.
</p><p>The equivalent of <code>cvs up</code> is:
</p>
<pre class="eval">hg pull -u
</pre>
<h3 name="Diffing_and_patching"> Diffing and patching </h3>
<ul><li> <code>hg diff</code> diffs the entire tree by default.  Use <code>hg diff .</code> (note the dot) to diff only the current directory.
</li></ul>
<ul><li> When applying a patch generated by Mercurial, use <code>patch -p1</code>, not <code>patch -p0</code>.  (This is due to a quirk of Mercurial diff output—it refers to fictional "a" and "b" directories.  Don't ask.)
</li></ul>
<p><code>hg</code> has no exact equivalent of <code>cvs diff -u8p</code>.  The simplest thing is <code>hg diff</code>, which provides 3 lines of context.
</p><p>To get 8 lines of context, enable the <code>hg extdiff</code> command (by editing your <code>~/.hgrc</code> file).  If you agree this is super lame, please leave a polite comment at http://www.selenic.com/mercurial/bts/issue654 .
</p>
<h3 name="Checking_in"> Checking in </h3>
<p>To commit your changes <i>to your local repository</i>:
</p>
<pre class="eval">hg commit
</pre>
<p>To push those changes upstream to the central repository:
</p>
<pre class="eval">hg push
</pre>
<p>For that to work, you have to have committer access, and you must edit the file <code><i>(your-local-hg-root)</i>/.hg/hgrc</code> to add this line:
</p>
<pre class="eval"><span class="plain">[paths]
default = http://hg.mozilla.org/mozilla-central/</span>
<b>default-push = <span class="plain">ssh://hg.mozilla.org/mozilla-central/</span></b>
</pre>
<p>You'll get a bogus error message each time you push:
</p>
<pre class="eval">remote: Could not chdir to home directory : No such file or directory
</pre>
<p>Just ignore it.
</p>
<h2 name="What_we_don.27t_have"> What we don't have </h2>
<p>There's no Bonsai for mozilla-central; but if you go to http://hg.mozilla.org/mozilla-central/ and click on "manifest", you can at least browse the tree and get "revisions" (change logs) or "annotate" (blame) for files.  (And it works for <i>any</i> repository, not just mozilla-central.)
</p><p>There's no LXR/MXR for mozilla-central.
</p><p>There's no Bugzilla integration for Mercurial.
</p>
<h2 name="See_also"> See also </h2>
<p>The <a class="external" href="http://hgbook.red-bean.com/hgbook.html">hg book</a> is the definitive Mercurial user guide.
</p><p><a href="Special:Tags?tag=Mercurial&amp;language=en">Category:Mercurial</a> lists the Mercurial-related articles on MDC.
</p><p>And on wiki.mozilla.org, these helpful pages:
</p>
<ul><li> {{mediawiki.interwiki('wikimo', 'Using_Mercurial_locally_with_CVS', 'Using Mercurial locally with CVS')}}, a how-to.
</li><li> {{mediawiki.interwiki('wikimo', 'Mercurial_on_Windows', 'Mercurial on Windows')}}
</li></ul>
Revert to this revision