Installing Mercurial

  • Revision slug: Installing_Mercurial
  • Revision title: Installing Mercurial
  • Revision id: 440289
  • Created:
  • Creator: wesj
  • Is current revision? No
  • Comment

Revision Content

{{ Note('If you have not yet read the Mercurial basics do so now, or see Mercurial for other resources.') }}

Installing

On Windows:
Mercurial comes with MozillaBuild, in the folder 'hg'.  See also wikimo:Mercurial on Windows.
Using a package manager:
If you use apt-get, emerge, port, yast, or yum to install software, just do the usual. If this gives you an old version (pre-1.5 -- check with hg version), you can update it using easy_install as follows:
  • Using apt-get:
    sudo apt-get install python-setuptools python-dev build-essential
    sudo easy_install -U mercurial
  • Using yum:
    sudo yum install python-setuptools python-devel.i686
    sudo easy_install -U mercurial
Other systems
Otherwise, the Mercurial binary packages are for you.

Basic configuration

You should configure Mercurial before pulling the code. Your mercurial configuration file should have at least the following settings:

[ui]
username = Your Real Name <user@example.com>
merge = your-merge-program (or internal:merge)
 
[diff]
git = 1
showfunc = 1
unified = 8

[defaults]
commit = -v

On Windows, these settings can be added to $HOME\.hgrc or $HOME\Mercurial.ini, or, if you'd like global settings, C:\mozilla-build\hg\Mercurial.ini or C:\Program Files\Mercurial\Mercurial.ini. On UNIX-like systems, they should be in your $HOME/.hgrc file.

You can configure the editor to use for commit messages using the editor option in the [ui] section or by setting the EDITOR environment variable.

If you are trying to access the repository through a proxy server, see these instructions.

Other configuration tips

Merge program

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.

A reasonable thing to do is to set ui.merge=internal:merge in the Mercurial configuration file (see below), which makes Mercurial try to merge changes and add the conflict markers (a la CVS) to the files that couldn't be merged.

Under Ubuntu, you can install meld package, then in in the Mercurial configuration file (see below) set ui.merge=meld

You can see the list of merge conflicts by looking for "merging ... failed!" in the update output.

Configuring kdiff3 as a merge tool

If you're on Linux and you have kdiff3 installed, you probably want to configure kdiff3 as a merge tool.  (It's better than meld because it will actually resolve a bunch of the conflicts without prompting you, generally quite accurately.)  You can do this by adding the following lines (which come from contrib/mergetools.hgrc in the Mercurial distribution):

[merge-tools]
kdiff3.args=--auto -L1 base --L2 local --L3 other $base $local $other -o $output
kdiff3.regkey=Software\KDiff3
kdiff3.regappend=\kdiff3.exe
kdiff3.fixeol=True
kdiff3.gui=True

Extensions

There's a number of extensions you can enable. See http://mercurial.selenic.com/wiki/UsingExtensions. Almost everyone should probably enable the following:

  • color - Colorize terminal output
  • histedit - Provides git rebase --interactive behavior.
  • pager - Feed command output into a pager (like less)
  • progress - Draw progress bars on long-running operations.
  • rebase - Ability to easily rebase patches on top of other heads.
  • transplant - Easily move patches between repositories, branches, etc.
  • mq - Easily maintain a series of patches on top of your tree, or even multiple different sets of patch queues. (see the Mercurial Queues guide to learn more)

These can all be turned on by just adding this to your .hgrc file:

[extensions]
color = 
rebase =
histedit =
progress =
transplant =
pager =
mq =

[defaults]
qnew = -U

[mq]
plain = True

In addition, there are some 3rd party extensions that are incredibly useful for basic development:

qcrecord
Provides a nice easy gui for splitting up patches into chunks. For a given patch you can type:
hg qcrefresh
mqext
Overrides qrefresh, qnew, qrename, qdelete, qimport, and qfinish to commit to your versioned patch queue automatically. This can be done through arguments to the commands, or automatically if you edit your .hgrc to include:
  [mqext]
  mqcommit = auto
It also includes commands to suggest reviewers (reviewers) and a bug component (components) for your patch, to find bugs touching the files you are modifying (bugs), to show a patch (qshow), and to show what files the current patch touches (qtouched).
trychooser
Automatically creates a try commit message and then pushes changes to Mozilla's Try infrastructure. Just run:
hg trychooser
qimportbz
Import patches from Bugzilla. Creates a filename and commit message for you based on the bug's metadata.
hg qimport bz://1234567
  
bzexport
Export patches to Bugzilla. There are quite a few optional arguments here to create new or update existing bugs with the attment, as well as auto matically request reviews. Type hg help bzexport for a full list but the basic syntax is:
hg bzexport -i 1234567

Installing these is fairly easy. You'll just need to find a place on your system to store the extensions, and clone the extension repos into it:

hg clone https://bitbucket.org/edgimar/crecord
hg clone https://bitbucket.org/sfink/mqext
hg clone https://hg.mozilla.org/users/robarnold_cmu.edu/qimportbz
hg clone https://hg.mozilla.org/users/tmielczarek_mozilla.com/bzexport
git clone https://github.com/pbiggar/trychooser

And then add then to your .hgrc file

[extensions]
qcrecord =  /path/to/crecord/crecord
mqext =  path/to/mqext
qimportbz =  path/to/qimportbz
bzexport =  path/to/bzexport
trychooser = path/to/trychooser/trychooser

Configuring the try repository

If you have access to the try server you may want to configure Mercurial so you can refer to it simply as "try", since it can be useful from all your trees.  This can be done by adding this to your ~/.hgrc (or Mercurial.ini):

 

[paths]
try = ssh://hg.mozilla.org/try/

You can also configure short names like this that are specific to a particular repository by adding a [paths] section to the .hg/hgrc file within a repository.  There are two magic names, "default" and "default-push", which are used as the default push/pull targets.  (If "default" is specified and "default-push" is not, "default" is used for both.)

Alternatively, you can install the trychooser extension (older version).

{{ languages( { "fr": "fr/Installation_de_Mercurial" } ) }}

Revision Source

<p>{{ Note('If you have not yet read the <a href="/en-US/docs/Mercurial_basics">Mercurial basics</a> do so now, or see <a href="/en-US/docs/Mercurial">Mercurial</a> for other resources.') }}</p>
<h2 id="Installing" name="Installing">Installing</h2>
<dl>
  <dt>
    On Windows:</dt>
  <dd>
    Mercurial comes with <a href="/En/Developer_Guide/Build_Instructions/Windows_Prerequisites#MozillaBuild_.2F_Pymake" title="En/Developer_Guide/Build_Instructions/Windows_Prerequisites#MozillaBuild_.2F_Pymake">MozillaBuild</a>, in the folder 'hg'.&nbsp; See also <a class="link-https" href="https://wiki.mozilla.org/Mercurial_on_Windows" title="https://wiki.mozilla.org/Mercurial_on_Windows">wikimo:Mercurial on Windows</a>.</dd>
  <dt>
    Using a package manager:</dt>
  <dd>
    If you use <code>apt-get</code>, <code>emerge</code>, <code>port</code>, <code>yast</code>, or <code>yum</code> to install software, just do the usual. If this gives you an old version (pre-1.5 -- check with <code>hg version</code>), you can update it using <code>easy_install</code> as follows:
    <ul>
      <li>Using apt-get:
        <pre class="eval">
sudo apt-get install python-setuptools python-dev build-essential
sudo easy_install -U mercurial</pre>
      </li>
      <li>Using yum:
        <pre class="eval">
sudo yum install python-setuptools python-devel.i686
sudo easy_install -U mercurial</pre>
      </li>
    </ul>
  </dd>
</dl>
<dl>
  <dt>
    Other systems</dt>
  <dd>
    Otherwise, the <a class="external" href="http://www.selenic.com/mercurial/wiki/index.cgi/BinaryPackages">Mercurial binary packages</a> are for you.</dd>
</dl>
<h2 id="Basic_configuration">Basic configuration</h2>
<p>You should configure Mercurial before pulling the code. Your mercurial configuration file should have at least the following settings:</p>
<pre class="eval">
[ui]
username = Your Real Name &lt;<a class="link-mailto" href="mailto:user@example.com" rel="freelink">user@example.com</a>&gt;
merge = <em>your-merge-program</em> (or internal:merge)
 
[diff]
git = 1
showfunc = 1
unified = 8

[defaults]
commit = -v
</pre>
<p>On Windows, these settings can be added to <code>$HOME\.hgrc</code> or <code>$HOME\Mercurial.ini</code>, or, if you'd like global settings, <code>C:\mozilla-build\hg\Mercurial.ini</code> or <code>C:\Program Files\Mercurial\Mercurial.ini</code>. On UNIX-like systems, they should be in your <code>$HOME/.hgrc</code> file.</p>
<p>You can configure the editor to use for commit messages using the <code>editor</code> option in the <code>[ui]</code> section or by setting the <code>EDITOR</code> environment variable.</p>
<p>If you are trying to access the repository through a proxy server, see <a class="external" href="http://www.selenic.com/mercurial/hgrc.5.html#http-proxy" title="http://www.selenic.com/mercurial/hgrc.5.html#http-proxy">these instructions</a>.</p>
<h2 id="Other_configuration_tips">Other configuration tips</h2>
<h3 id="Merge_program" name="Merge_program">Merge program</h3>
<p>After installing, <strong>choose a <a class="external" href="http://www.selenic.com/mercurial/wiki/index.cgi/MergeProgram">merge program</a></strong>. 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>A reasonable thing to do is to set <code>ui.merge=internal:merge</code> in the Mercurial configuration file (see below), which makes Mercurial try to merge changes and add the conflict markers (a la CVS) to the files that couldn't be merged.</p>
<p>Under Ubuntu, you can install meld package, then in in the Mercurial configuration file (see below) set <code>ui.merge=meld</code></p>
<p>You can see the list of merge conflicts by looking for "merging ... failed!" in the update output.</p>
<h4 id="Configuring_kdiff3_as_a_merge_tool">Configuring kdiff3 as a merge tool</h4>
<p>If you're on Linux and you have kdiff3 installed, you probably want to configure kdiff3 as a merge tool.&nbsp; (It's better than meld because it will actually resolve a bunch of the conflicts without prompting you, generally quite accurately.)&nbsp; You can do this by adding the following lines (which come from <code>contrib/mergetools.hgrc</code> in the Mercurial distribution):</p>
<pre>
[merge-tools]
kdiff3.args=--auto -L1 base --L2 local --L3 other $base $local $other -o $output
kdiff3.regkey=Software\KDiff3
kdiff3.regappend=\kdiff3.exe
kdiff3.fixeol=True
kdiff3.gui=True

</pre>
<h3 id="Extensions">Extensions</h3>
<p>There's a number of extensions you can enable. See <a href="http://mercurial.selenic.com/wiki/UsingExtensions" title="http://mercurial.selenic.com/wiki/UsingExtensions">http://mercurial.selenic.com/wiki/UsingExtensions</a>. Almost everyone should probably enable the following:</p>
<ul>
  <li>color - Colorize terminal output</li>
  <li>histedit - Provides <em>git rebase --interactive</em> behavior.</li>
  <li>pager - Feed command output into a pager (like <em>less</em>)</li>
  <li>progress - Draw progress bars on long-running operations.</li>
  <li>rebase - Ability to easily rebase patches on top of other heads.</li>
  <li>transplant - Easily move patches between repositories, branches, etc.</li>
  <li>mq - Easily maintain a series of patches on top of your tree, or even multiple different sets of patch queues. (see the <a href="/en-US/docs/Mercurial_Queues" title="/en-US/docs/Mercurial_Queues">Mercurial Queues</a> guide to learn more)</li>
</ul>
<p>These can all be turned on by just adding this to your .hgrc file:</p>
<pre>
[extensions]
color = 
rebase =
histedit =
progress =
transplant =
pager =
mq =

[defaults]
qnew = -U

[mq]
plain = True</pre>
<p>In addition, there are some 3rd party extensions that are incredibly useful for basic development:</p>
<dl>
  <dt>
    <a href="https://bitbucket.org/edgimar/crecord">qcrecord</a></dt>
  <dd>
    Provides a nice easy gui for splitting up patches into chunks. For a given patch you can type:
    <pre>
hg qcrefresh
</pre>
  </dd>
  <dt>
    <a href="https://bitbucket.org/sfink/mqext">mqext</a></dt>
  <dd>
    Overrides <code>qrefresh</code>, <code>qnew</code>, <code>qrename</code>, <code>qdelete</code>, <code>qimport</code>, and <code>qfinish</code> to commit to your <a href="https://developer.mozilla.org/en-US/docs/Creating_Mercurial_User_Repositories" title="https://developer.mozilla.org/en-US/docs/Creating_Mercurial_User_Repositories">versioned patch queue</a> automatically. This can be done through arguments to the commands, or automatically if you edit your .hgrc to include:
    <pre>
  [mqext]
  mqcommit = auto
</pre>
    It also includes commands to suggest reviewers (<code>reviewers</code>) and a bug component (<code>components</code>) for your patch, to find bugs touching the files you are modifying (<code>bugs</code>), to show a patch (<code>qshow</code>), and to show what files the current patch touches (<code>qtouched</code>).</dd>
  <dt>
    <a href="https://github.com/pbiggar/trychooser">trychooser</a></dt>
  <dd>
    Automatically creates a try commit message and then pushes changes to Mozilla's Try infrastructure. Just run:
    <pre>
hg trychooser</pre>
  </dd>
  <dt>
    <a href="https://hg.mozilla.org/users/robarnold_cmu.edu/qimportbz">qimportbz</a></dt>
  <dd>
    Import patches from Bugzilla. Creates a filename and commit message for you based on the bug's metadata.
    <pre>
hg qimport bz://1234567
  </pre>
  </dd>
  <dt>
    <a href="https://hg.mozilla.org/users/tmielczarek_mozilla.com/bzexport">bzexport</a></dt>
  <dd>
    Export patches to Bugzilla. There are quite a few optional arguments here to create new or update existing bugs with the attment, as well as auto matically request reviews. Type hg help bzexport for a full list but the basic syntax is:
    <pre>
hg bzexport -i 1234567</pre>
  </dd>
</dl>
<p>Installing these is fairly easy. You'll just need to find a place on your system to store the extensions, and clone the extension repos into it:</p>
<pre>
hg clone https://bitbucket.org/edgimar/crecord
hg clone https://bitbucket.org/sfink/mqext
hg clone https://hg.mozilla.org/users/robarnold_cmu.edu/qimportbz
hg clone https://hg.mozilla.org/users/tmielczarek_mozilla.com/bzexport
git clone https://github.com/pbiggar/trychooser
</pre>
<p>And then add then to your .hgrc file</p>
<pre>
[extensions]
qcrecord =  /path/to/crecord/crecord
mqext =  path/to/mqext
qimportbz =  path/to/qimportbz
bzexport =  path/to/bzexport
trychooser = path/to/trychooser/trychooser
</pre>
<h3 id="Configuring_the_try_repository">Configuring the try repository</h3>
<p>If you have access to the <a class="link-https" href="https://wiki.mozilla.org/Build:TryServer" title="https://wiki.mozilla.org/Build:TryServer">try server</a> you may want to configure Mercurial so you can refer to it simply as "try", since it can be useful from all your trees.&nbsp; This can be done by adding this to your ~/.hgrc (or Mercurial.ini):</p>
<p>&nbsp;</p>
<pre>
[paths]
try = ssh://hg.mozilla.org/try/
</pre>
<p>You can also configure short names like this that are specific to a particular repository by adding a [paths] section to the .hg/hgrc file within a repository.&nbsp; There are two magic names, "default" and "default-push", which are used as the default push/pull targets.&nbsp; (If "default" is specified and "default-push" is not, "default" is used for both.)</p>
<p>Alternatively, you can install the <a class="link-https" href="https://bitbucket.org/sfink/trychooser" title="https://bitbucket.org/sfink/trychooser">trychooser extension</a> (<a class="link-https" href="https://github.com/pbiggar/trychooser" title="https://github.com/pbiggar/trychooser">older version</a>).</p>
<p>{{ languages( { "fr": "fr/Installation_de_Mercurial" } ) }}</p>
Revert to this revision