Using Mercurial

  • Revision slug: Mercurial_FAQ
  • Revision title: Using Mercurial
  • Revision id: 11228
  • Created:
  • Creator: Jorend
  • Is current revision? No
  • Comment no wording changes

Revision Content

How is Mercurial different from CVS?

  • "Very". You should read and understand Mercurial basics before undertaking work with Mercurial that you care about.
  • 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 (docs) 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.

How do I install Mercurial?

If you use apt-get, emerge, port, or yum to install software, just do the usual. If this gives you an old version (pre-1.0 -- check with hg version), you can update it using easy_install as follows (using apt-get in this example):

sudo apt-get install python-setuptools python-dev build-essential
sudo easy_install -U mercurial

Otherwise, the Mercurial binary packages are for you. See also {{ mediawiki.interwiki('wikimo', 'Mercurial_on_Windows', 'wikimo:Mercurial on Windows') }}.

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.

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

Configuration

You should configure Mercurial before pulling the code. Your Mercurial configuration file (~/.hgrc) should have at least the following settings:

[ui]
username = Your Real Name <user@example.com>
merge = your-merge-program

[diff]
git = 1

[defaults]
diff=-p -U 8

On Windows, these settings can be added to 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 {{ mediawiki.external('ui') }} section or by setting the EDITOR environment variable.

What's the difference between hg pull and hg update?

hg-diagram.png

hg pull copies changesets from one repository to another.  It only brings changes into your local repository, not your working copy.  It will touch the network if you're pulling from a remote repository.

hg update updates your working copy.  It only modifies your working copy.  It will not touch the network (unless your directory is on a network filesystem).

How does Mercurial handle line endings?

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.

(How about a pre-commit hook that rejects pushes containing CR with a suitably informative error message? We possibly want to make exceptions for certain types of files (at least binary files of course), but we can tweak the hook as necessary as these crop up. Mercurial 1.0 adds a standard hook for this in the win32text extension that we could use/adapt. --jwatt)

How can I...

How can I check out Mozilla?

The Mozilla 2 trunk is located at http://hg.mozilla.org/mozilla-central/ . See Mozilla Source Code (Mercurial) for instructions for checking out Mozilla 2 source from Mercurial.

How can I edit and update files?

You can randomly edit files in the working directory, just like with CVS.

The common command to update a tree is:

hg pull -u

It is not possible to update only one directory; you have to update the entire tree.

How can I diff and patch files?

  • hg diff diffs the entire tree by default. Use hg diff <dir> to diff only the given directory. Don't forget to hg add any new files you are adding before generating the patch.
  • If you are changing binary files or renaming files you may want to use git style patches with hg diff -g to retain that sort of information in the patch.
  • 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.).
  • If you have a git style patch with renames and/or binary changes you can use hg import --no-commit to apply the patch to your tree or use hg qimport to import the patch to mq.

Preferred diff options are hg diff -p -U 8 which includes 8 lines of context and shows the relevant function for the block. You can make these options default in the Mercurial configuration file.

How do I check stuff in?

Required configuration

Before committing any changes, add these lines to your ~/.hgrc file:

[ui]
username = Your Name <your.email@example.com>

To push to mozilla-central and other mozilla-hosted repositories you have to have committer access, and you must edit the file (your-local-hg-root)/.hg/hgrc (note, this is NOT your ~/.hgrc) to add this line:

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

You also have to tell ssh what username to use when connecting to hg.mozilla.org. This should be the username associated with your Mozilla LDAP account. You can do this either by making the default-push path above more complicated (user@host.name@hg.mozilla.org) or by adding lines to your ~/.ssh/config :

Host hg.mozilla.org
User user@host.domain

Check what you're going to commit

Next, to check if you're really committing what you want to commit (especially important when doing merges or other trickier commits):

hg status
hg diff

status shows the files that have changed in your working directory compared to what's in your repository (the parent revisions, which you can see by using hg parents). hg diff shows the actual changes in those files, as unified diffs. You can add a -U8 option to see more context.

Commit to the local repository

As the next step, you will commit your changes to your local repository:

hg commit

This commits every change reported by hg status. You can limit the commit to specific files or directories using hg commit filenames. You can commit on behalf of someone else using hg commit -u "Someone Else <someone@example.com>". See hg help commit for more details.

To add new files to the repository and to remove obsolete ones use

hg addremove

Check what you're going to push

Before you push, you likely want to check what changesets will be pushed. You can do this using the outgoing command:

hg outgoing

This will give you a list of changesets that will be pushed to the default remote repository. Add a repository argument to see outgoing changesets for another repository.

Push to the central repository

To push those changes upstream to the central repository:

hg push

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.

How do I deal with "abort: push creates new remote heads!"?

Whatever you do, don't do 'push -f' like the message suggests. (It'll probably fail anyway, but don't try it.)

Someone pushed new commits upstream since your last pull. You then committed your patch locally and are trying to push that commit upstream; that upstream has a different commit that you started from.

  YOU ---> o  9123b7791b52 - Kaitlin Jones <kaitlin@example.net> - Bug 123456 - Trebled fromps (r=gavin)
           | 
TRUNK ---> | o  306726089e22 - Robert Longson <longsonr@example.com> - Bug 437448. New-style nsSVGString
           | | 
           | o  ba9b9a7c52a5 - Robert Longson <longsonr@example.com> - Bug 437448. New-style nsSVGString
           |/
           o  f8f4360bf155 - Robert O'Callahan <robert@example.org> - Bug 421436. Remove hack that gives

There are two things you can do. The simpler way is to merge your commits: run hg pull, then hg merge. If there are any merge conflicts, hg will open a merge program to try to help you resolve them manually. (If you fail to make sense of the merge tool, that's OK.  Just close it; hg will detect that the conflicts weren't all resolved and spit out some hg update -C commands that you can use to undo and then retry the busted merge.)

Even if there were no conflicts, you have to commit the merge: hg commit -m "Merge bug 123456".

  YOU ---> o 1fe7659c29a9 - Kaitlin Jones <kaitlin@example.net> - Merge bug 123456.
           |\
           o | 9123b7791b52 - Kaitlin Jones <kaitlin@example.net> - Bug 123456 - Trebled fromps (r=gavin)
           | |
TRUNK ---> | o  306726089e22 - Robert Longson <longsonr@example.com> - Bug 437448. New-style nsSVGString
           | | 
           | o  ba9b9a7c52a5 - Robert Longson <longsonr@example.com> - Bug 437448. New-style nsSVGString
           |/
           o  f8f4360bf155 - Robert O'Callahan <robert@example.org> - Bug 421436. Remove hack that gives

Now you can hg push as normal.

This is the simplest and safest thing to do. It leaves a merge commit in the log, which some people find annoying.  Nonetheless merging is the recommended fix for this problem.

There is another approach, but it's considerably more arcane -- a fix/replacement is in the works.

{{ Warning("This next approach mostly works fine, but there have been reports of patches being eaten at various times. Take steps to back up your patch (perhaps by obtaining a diff: hg log -p -r 12345 to show the patch for rev 12345) until you\'re sure things work like you expect.") }}

The more advanced thing you can do is to import the commit into mq, pop it off the queue, update, and then commit it again before pushing:

% hg log -l 5
415[tip]   d1accb6ee840   2008-04-30 09:57 -0700   vladimir
  b=430873; fast path drawImage with a canvas as source
414   3a3ecbb4873e   2008-04-30 09:55 -0700   vladimir
  cvs sync
% hg qimport -r 415
% hg qtop
415.diff
% hg qpop
Patch queue now empty
% hg pull -u
... various pull/update messages ...
% hg qpush
applying 415.diff
Now at: 415.diff
Fix up conficts as necessary; if you fixed up any, run hg qrefresh first
% hg qrm -r 415.diff
qrm -r means "remove this patch from my queue, but keep the revision"
% hg log -l 5
verify that the log looks good, with your commit on top
% hg push

If you already use mq to manage your patches, then just make sure you pull/update right before committing and pushing your patch. If you have problems with the above, it's ok to just do a simple merge as described previously.

How do I deal with "not updating since new heads added (run 'hg heads' to see heads, run 'hg merge' to merge)"?

This was caused by the creation of a new named branch in the repository since your last pull.  This is also due to pulling and updating via hg pull -u instead of via hg pull; hg up. This is a known bug in the current Mercurial.  

If you still want to remain on the tip, run:

hg up

See Also: Release branches in Mozilla-Central 

How do I see what these commands will do before I do them?

If you want to see what hg commit will commit, run hg diff first.

If you want to see what hg push will push, run hg outgoing first.

If you want to see what hg pull will pull, run hg incoming first.

These pairs of commands all take similar arguments, for good reason. These are a good idea to use all the time when you're learning mercurial. And even once you're an expert, always doing outgoing before push is a good idea.

How can I customize the format of the patches Mercurial creates?

Edit your ~/.hgrc file and add some lines like these:

[defaults]
diff=-U 8 -p
qdiff=-U 8

[diff]
git=true

The {{ mediawiki.external('defaults') }} section affects the default output of the hg diff and hg qdiff commands. The options behave the same as they would on the command line. Try hg help diff for more info.

The {{ mediawiki.external('diff') }} section affects all patches generated by Mercurial, even those generated for Mercurial's internal use. You need to be a lot more careful with this, but git=true is recommended. Without it, Mercurial cannot diff binary files and does not track the execute mode bit.

How do I get a diff -w?

There is a known issue with hg diff -w where it doesn't work.

To get around this add the following to your ~/.hgrc file, editing existing sections where applicable:

[extensions]
hgext.extdiff =

[extdiff]
cmd.diffw = diff
opts.diffw = -w

You can, of course, add your other favourite diff options to opts.diffw. Once you've added this, you will now have a new hg command, hg diffw.

Backing out changes

Reverting the whole tree to a known-good revision

It's easy, like using a sledgehammer is easy. But this is usually overkill.

$$$$ hg pull -u
$$$$ hg revert --all -r a0193d83c208       # use your known-good revision id here
$$$$ hg commit                             # be kind, include the revision id in your commit message
$$$$ hg push

There's a more precise alternative:

Backing out a single changeset

Suppose changeset f8f4360bf155 broke something.

$$$$ hg pull -u
$$$$ hg backout f8f4360bf155               # use the revision id of the bad change here

This creates and commits a new changeset that reverts all the changes in that revision.

If you see this message:

the backout changeset is a new head - do not forget to merge

That means you need to merge, because your history now looks like this:

  YOU ---> o  9123b7791b52 - Kaitlin Jones <kaitlin@example.net> - Backed out changeset f8f4360bf155
           | 
TRUNK ---> | o  4e5bfb83643f - Simon Montagu <smontagu@example.org> - imported patch 435856
           | | 
           | o  6ee23de41631 - Phil Ringnalda <philringnalda@example.com> - Bug 438526 - Opening links w
           | | 
           | o  22baa05d0e8a - Robert O'Callahan <robert@example.org> - Remove DOM testcase from exclusi
           | | 
           | o  c1aec2094f7e - Robert Longson <longsonr@example.com> - Bug 437448. New-style nsSVGString
           | | 
           | o  306726089e22 - Robert Longson <longsonr@example.com> - Bug 437448. New-style nsSVGString
           | | 
           | o  ba9b9a7c52a5 - Robert Longson <longsonr@example.com> - Bug 437448. New-style nsSVGString
           |/
           o  f8f4360bf155 - Robert O'Callahan <robert@example.org> - Bug 421436. Remove hack that gives
           |
           ⋮ (the past)

Your backout changeset is based on an old revision. It doesn't contain more recent changes.

Handle this like any other merge. If you've never done a merge before, get help. (It could be trivial or it could be a huge headache. There's plenty about merging elsewhere in this FAQ.)

Help

Help, I can't push!

If you're trying to push, and you can't, first try this:

$$$$ ssh hg.mozilla.org

If you see output like:

Permission denied (publickey,gssapi-with-mic).

it may have the following reasons:

If you see output like:

You are not allowed to use this system, go away!

then you need to file a bug in mozilla.org:Server Operations.

You should expect the ssh command to disconnect you immediately, since you're not supposed to have shell access. It may give the output:

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

which is harmless (although some people see it and some people don't).

If you see output like:

ssl required

then you need to configure your default-push correctly.

Things that have changed

  • Bonsai is replaced by the Hg web viewer. This lacks some bonsai features that would be nice, including mark, line-number anchors, and graphs. There are some terminology differences:

bonsai blame == hg annotate
bonsai log == hg revisions
also you can browse the repository using the "manifest" link.

  • There's no Bugzilla integration for Mercurial.

{{ languages( { "es": "es/FAQ_de_Mercurial" } ) }}

Revision Source

<h3 name="How_is_Mercurial_different_from_CVS.3F">How is Mercurial different from CVS?</h3>
<ul> <li>"Very". You should read and understand <a href="/en/Mercurial_basics" title="en/Mercurial_basics">Mercurial basics</a> before undertaking work with Mercurial that you care about.</li>
</ul>
<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" title="en/Publishing_Mercurial_Clones">Publishing Mercurial Clones</a>.)</li>
</ul>
<ul> <li>With Mercurial, a complete, fully armed and operational <em>clone</em> 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> <p><a href="/en/Mercurial_Queues" title="en/Mercurial_Queues">Mercurial queues</a> (<a class="external" href="http://hgbook.red-bean.com/hgbookch12.html#x16-26700012">docs</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:</p> <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><strong>We hope Mercurial will allow us to rethink the way we work.</strong> 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>
<h3 name="How_do_I_install_Mercurial.3F">How do I install 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 this gives you an old version (pre-1.0 -- check with <code>hg version</code>), you can update it using <code>easy_install</code> as follows (using <code>apt-get</code> in this example):</p>
<pre class="eval">sudo apt-get install python-setuptools python-dev build-essential
sudo easy_install -U mercurial
</pre>
<p>Otherwise, the <a class="external" href="http://www.selenic.com/mercurial/wiki/index.cgi/BinaryPackages">Mercurial binary packages</a> are for you. See also {{ mediawiki.interwiki('wikimo', 'Mercurial_on_Windows', 'wikimo:Mercurial on Windows') }}.</p>
<h4 name="Merge_program">Merge program</h4>
<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>You can see the list of merge conflicts by looking for "merging ... failed!" in the update output.</p>
<h4 name="Configuration">Configuration</h4>
<p>You should configure Mercurial before pulling the code. Your Mercurial configuration file (<code>~/.hgrc</code>) should have at least the following settings:</p>
<pre class="eval">[ui]
username = Your Real Name <span class="nowiki">&lt;user@example.com&gt;</span>
merge = <em>your-merge-program</em>

[diff]
git = 1

[defaults]
diff=-p -U 8
</pre>
<p>On Windows, these settings can be added to <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>{{ mediawiki.external('ui') }}</code> section or by setting the <code>EDITOR</code> environment variable.</p>
<h3 name="How_does_Mercurial_handle_line_endings.3F">What's the difference between hg pull and hg update?</h3>
<p><img alt="hg-diagram.png" class="internal default" src="/@api/deki/files/3040/=hg-diagram.png" style="margin-left: 50px; margin-top: 20px; width: 405px; height: 222px;"></p>
<p><code>hg pull</code> copies changesets from one repository to another.  It only brings changes into your local <em>repository</em>, not your working copy.  It will touch the network if you're pulling from a remote repository.</p>
<p><code>hg update</code> updates your working copy.  It only modifies your working copy.  It will not touch the network (unless your directory is on a network filesystem).</p><h3 name="How_does_Mercurial_handle_line_endings.3F">How does Mercurial handle line endings?</h3>
<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>
<p>(How about a pre-commit hook that rejects pushes containing CR with a suitably informative error message? We possibly want to make exceptions for certain types of files (at least binary files of course), but we can tweak the hook as necessary as these crop up. Mercurial 1.0 adds a standard hook for this in the win32text extension that we could use/adapt. --jwatt)</p>
<h2 name="How_can_I...">How can I...</h2>
<h3 name="How_can_I_check_out_Mozilla.3F">How can I check out Mozilla?</h3>
<p>The Mozilla 2 trunk is located at <a class=" external" href="http://hg.mozilla.org/mozilla-central/" rel="freelink">http://hg.mozilla.org/mozilla-central/</a> . See <a href="/en/Mozilla_Source_Code_(Mercurial)" title="en/Mozilla_Source_Code_(Mercurial)">Mozilla Source Code (Mercurial)</a> for instructions for checking out Mozilla 2 source from Mercurial.</p>
<h3 name="How_can_I_edit_and_update_files.3F">How can I edit and update files?</h3>
<p>You can randomly edit files in the working directory, just like with CVS.</p>
<p>The common command to update a tree is:</p>
<pre class="eval">hg pull -u
</pre>
<p>It is not possible to update only one directory; you have to update the entire tree.</p>
<h3 name="How_can_I_diff_and_patch_files.3F">How can I diff and patch files?</h3>
<ul> <li><code>hg diff</code> diffs the entire tree by default. Use <code>hg diff &lt;dir&gt;</code> to diff only the given directory. Don't forget to <code>hg add</code> any new files you are adding before generating the patch.</li>
</ul>
<ul> <li>If you are changing binary files or renaming files you may want to use git style patches with <code>hg diff -g</code> to retain that sort of information in the patch.</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>
<ul> <li>If you have a git style patch with renames and/or binary changes you can use <code>hg import --no-commit</code> to apply the patch to your tree or use <code>hg qimport</code> to import the patch to mq.</li>
</ul>
<p>Preferred diff options are <code>hg diff -p -U 8</code> which includes 8 lines of context and shows the relevant function for the block. You can make these options default in the <a class="internal" href="/en/Mercurial_FAQ#Configuration" title="en/Mercurial FAQ#Configuration">Mercurial configuration file</a>.</p>
<h3 name="How_do_I_check_stuff_in.3F">How do I check stuff in?</h3>
<h4 name="Required_configuration">Required configuration</h4>
<p>Before committing any changes, add these lines to your <code>~/.hgrc</code> file:</p>
<pre class="eval">[ui]
username = Your Name &lt;<a class=" link-mailto" href="mailto:your.email@example.com" rel="freelink">your.email@example.com</a>&gt;
</pre>
<p>To push to <a href="/en/mozilla-central" title="en/mozilla-central">mozilla-central</a> and other mozilla-hosted repositories you have to have committer access, and you must edit the file <code><em>(your-local-hg-root)</em>/.hg/hgrc</code> (note, this is <strong>NOT</strong> your <code>~/.hgrc</code>) to add this line:</p>
<pre class="eval">[paths]
default = <span class="nowiki">http://hg.mozilla.org/mozilla-central/</span>
<strong>default-push = <span class="nowiki">ssh://hg.mozilla.org/mozilla-central/</span></strong>
</pre>
<p>You also have to tell ssh what username to use when connecting to hg.mozilla.org. This should be the username associated with your Mozilla LDAP account. You can do this either by making the default-push path above more complicated <a class=" link-mailto" href="mailto:(user@host.name" rel="freelink">(user@host.name</a>@hg.mozilla.org) or by adding lines to your ~/.ssh/config :</p>
<pre class="eval">Host hg.mozilla.org
User <a class=" link-mailto" href="mailto:user@host.domain" rel="freelink">user@host.domain</a>
</pre>
<h4 name="Check_what_you.27re_going_to_commit">Check what you're going to commit</h4>
<p>Next, to check if you're really committing what you want to commit (especially important when doing merges or other trickier commits):</p>
<pre class="eval">hg status
hg diff
</pre>
<p><code>status</code> shows the files that have changed in your working directory compared to what's in your repository (the parent revisions, which you can see by using <code>hg parents</code>). <code>hg diff</code> shows the actual changes in those files, as unified diffs. You can add a -U8 option to see more context.</p>
<h4 name="Commit_to_the_local_repository">Commit to the local repository</h4>
<p>As the next step, you will commit your changes <em>to your local repository</em>:</p>
<pre class="eval">hg commit
</pre>
<p>This commits every change reported by <code>hg status</code>. You can limit the commit to specific files or directories using <code>hg commit <em>filenames</em></code>. You can commit on behalf of someone else using <code>hg commit -u "Someone Else &lt;<a class=" link-mailto" href="mailto:someone@example.com" rel="freelink">someone@example.com</a>&gt;"</code>. See <code>hg help commit</code> for more details.</p>
<p>To add new files to the repository and to remove obsolete ones use</p>
<pre class="eval">hg addremove
</pre>
<h4 name="Check_what_you.27re_going_to_push">Check what you're going to push</h4>
<p>Before you push, you likely want to check what changesets will be pushed. You can do this using the <code>outgoing</code> command:</p>
<pre class="eval">hg outgoing
</pre>
<p>This will give you a list of changesets that will be pushed to the default remote repository. Add a repository argument to see outgoing changesets for another repository.</p>
<h4 name="Push_to_the_central_repository">Push to the central repository</h4>
<p>To push those changes upstream to the central repository:</p>
<pre class="eval">hg push
</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>
<h3 name="How_do_I_deal_with_.22abort:_push_creates_new_remote_heads.21.22.3F">How do I deal with "abort: push creates new remote heads!"?</h3>
<p>Whatever you do, don't do 'push -f' like the message suggests. (It'll probably fail anyway, but don't try it.)</p>
<p>Someone pushed new commits upstream since your last pull. You then committed your patch locally and are trying to push that commit upstream; that upstream has a different commit that you started from.</p>
<pre>  <strong>YOU</strong> ---&gt; o  9123b7791b52 - Kaitlin Jones <span class="plain">&lt;kaitlin@example.net&gt;</span> - Bug 123456 - Trebled fromps (r=gavin)
           | 
<strong>TRUNK</strong> ---&gt; | o  306726089e22 - Robert Longson <span class="plain">&lt;longsonr@example.com&gt;</span> - Bug 437448. New-style nsSVGString
           | | 
           | o  ba9b9a7c52a5 - Robert Longson <span class="plain">&lt;longsonr@example.com&gt;</span> - Bug 437448. New-style nsSVGString
           |/
           o  f8f4360bf155 - Robert O'Callahan <span class="plain">&lt;robert@example.org&gt;</span> - Bug 421436. Remove hack that gives</pre>
<p>There are two things you can do. The simpler way is to merge your commits: run <code>hg pull</code>, then <code>hg merge</code>. If there are any merge conflicts, hg will open a merge program to try to help you resolve them manually. (If you fail to make sense of the merge tool, that's OK.  Just close it; hg will detect that the conflicts weren't all resolved and spit out some <code>hg update -C</code> commands that you can use to undo and then retry the busted merge.)</p>
<p>Even if there were no conflicts, you have to commit the merge: <code>hg commit -m "Merge bug 123456"</code>.</p>
<pre>  <strong>YOU</strong> ---&gt; o 1fe7659c29a9 - Kaitlin Jones <span class="plain">&lt;kaitlin@example.net&gt;</span> - Merge bug 123456.
           |\
           o | 9123b7791b52 - Kaitlin Jones <span class="plain">&lt;kaitlin@example.net&gt;</span> - Bug 123456 - Trebled fromps (r=gavin)
           | |
<strong>TRUNK</strong> ---&gt; | o  306726089e22 - Robert Longson <span class="plain">&lt;longsonr@example.com&gt;</span> - Bug 437448. New-style nsSVGString
           | | 
           | o  ba9b9a7c52a5 - Robert Longson <span class="plain">&lt;longsonr@example.com&gt;</span> - Bug 437448. New-style nsSVGString
           |/
           o  f8f4360bf155 - Robert O'Callahan <span class="plain">&lt;robert@example.org&gt;</span> - Bug 421436. Remove hack that gives</pre>
<p>Now you can <code>hg push</code> as normal.</p>
<p>This is the simplest and safest thing to do. It leaves a merge commit in the log, which some people find annoying.  Nonetheless merging is the recommended fix for this problem.</p>
<p>There is another approach, but it's considerably more arcane -- a fix/replacement is in the works.</p>
<p>{{ Warning("This next approach mostly works fine, but there have been reports of patches being eaten at various times. Take steps to back up your patch (perhaps by obtaining a diff: hg log -p -r 12345 to show the patch for rev 12345) until you\'re sure things work like you expect.") }}</p>
<p>The more advanced thing you can do is to import the commit into <a class="external" href="http://www.selenic.com/mercurial/wiki/index.cgi/MqExtension">mq</a>, pop it off the queue, update, and then commit it again before pushing:</p>
<pre class="eval">% <strong>hg log -l 5</strong>
415[tip]   d1accb6ee840   2008-04-30 09:57 -0700   vladimir
  b=430873; fast path drawImage with a canvas as source
414   3a3ecbb4873e   2008-04-30 09:55 -0700   vladimir
  cvs sync
% <strong>hg qimport -r 415</strong>
% <strong>hg qtop</strong>
415.diff
% <strong>hg qpop</strong>
Patch queue now empty
% <strong>hg pull -u</strong>
<em>... various pull/update messages ...</em>
% <strong>hg qpush</strong>
applying 415.diff
Now at: 415.diff
<em>Fix up conficts as necessary; if you fixed up any, run hg qrefresh first</em>
% <strong>hg qrm -r 415.diff</strong>
<em>qrm -r means "remove this patch from my queue, but keep the revision"</em>
% <strong>hg log -l 5</strong>
<em>verify that the log looks good, with your commit on top</em>
% <strong>hg push</strong>
</pre>
<p>If you already use mq to manage your patches, then just make sure you pull/update right before committing and pushing your patch. If you have problems with the above, it's ok to just do a simple merge as described previously.</p>
<h3>How do I deal with "not updating since new heads added (run 'hg heads' to see heads, run 'hg merge' to merge)"?</h3>
<p>This was caused by the creation of a new named branch in the repository since your last pull.  This is also due to pulling and updating via <code>hg pull -u </code>instead of via <code>hg pull; hg up. </code>This is a known bug in the current Mercurial.  </p>
<p>If you still want to remain on the tip, run:</p>
<pre>hg up</pre>
<p>See Also: <a class="external" href="http://benjamin.smedbergs.us/blog/2008-10-09/release-branches-in-mozilla-central/" title="http://benjamin.smedbergs.us/blog/2008-10-09/release-branches-in-mozilla-central/">Release branches in Mozilla-Central</a> </p>
<h3 name="How_do_I_see_what_these_commands_will_do_before_I_do_them.3F"><span id="1224048115147S" style="display: none;"> </span>How do I see what these commands will do before I do them?</h3>
<p>If you want to see what <code>hg commit</code> will commit, run <code>hg diff</code> first.</p>
<p>If you want to see what <code>hg push</code> will push, run <code>hg outgoing</code> first.</p>
<p>If you want to see what <code>hg pull</code> will pull, run <code>hg incoming</code> first.</p>
<p>These pairs of commands all take similar arguments, for good reason. These are a good idea to use all the time when you're learning mercurial. And even once you're an expert, always doing outgoing before push is a good idea.</p>
<h3 name="How_can_I_customize_the_format_of_the_patches_Mercurial_creates.3F">How can I customize the format of the patches Mercurial creates?</h3>
<p>Edit your <code>~/.hgrc</code> file and add some lines like these:</p>
<pre class="eval">[defaults]
diff=-U 8 -p
qdiff=-U 8

[diff]
git=true
</pre>
<p>The <code>{{ mediawiki.external('defaults') }}</code> section affects the default output of the <code>hg diff</code> and <code>hg qdiff</code> commands. The options behave the same as they would on the command line. Try <code>hg help diff</code> for more info.</p>
<p>The <code>{{ mediawiki.external('diff') }}</code> section affects all patches generated by Mercurial, even those generated for Mercurial's internal use. You need to be a lot more careful with this, but <code>git=true</code> is recommended. Without it, Mercurial cannot diff binary files and does not track the execute mode bit.</p>
<h3>How do I get a diff -w?</h3>
<p>There is a <a class="external" href="http://www.selenic.com/mercurial/bts/issue127" title="http://www.selenic.com/mercurial/bts/issue127">known issue</a> with <code>hg diff -w</code> where it doesn't work.</p>
<p>To get around this add the following to your <code>~/.hgrc</code> file, editing existing sections where applicable:</p>
<pre>[extensions]
hgext.extdiff =

[extdiff]
cmd.diffw = diff
opts.diffw = -w
</pre>
<p>You can, of course, add your other favourite diff options to <code>opts.diffw</code>. Once you've added this, you will now have a new hg command, <code>hg diffw</code>.</p>
<h2 name="Backing_out_changes">Backing out changes</h2>
<h3 name="Reverting_the_whole_tree_to_a_known-good_revision">Reverting the whole tree to a known-good revision</h3>
<p>It's easy, like using a sledgehammer is easy. But this is usually overkill.</p>
<pre class="eval">$$$$ hg pull -u
$$$$ <strong>hg revert --all -r a0193d83c208</strong>       <em># use your known-good revision id here</em>
$$$$ hg commit                             <em># be kind, include the revision id in your commit message</em>
$$$$ hg push
</pre>
<p>There's a more precise alternative:</p>
<h3 name="Backing_out_a_single_changeset">Backing out a single changeset</h3>
<p>Suppose changeset <code>f8f4360bf155</code> broke something.</p>
<pre class="eval">$$$$ hg pull -u
$$$$ <strong>hg backout f8f4360bf155</strong>               <em># use the revision id of the bad change here</em>
</pre>
<p>This creates and commits a new changeset that reverts all the changes in that revision.</p>
<p>If you see this message:</p>
<pre class="eval">the backout changeset is a new head - do not forget to merge
</pre>
<p>That means you need to merge, because your history now looks like this:</p>
<pre class="eval">  <strong>YOU</strong> ---&gt; o  9123b7791b52 - Kaitlin Jones &lt;<a class=" link-mailto" href="mailto:kaitlin@example.net" rel="freelink">kaitlin@example.net</a>&gt; - Backed out changeset f8f4360bf155
           | 
<strong>TRUNK</strong> ---&gt; | o  4e5bfb83643f - Simon Montagu &lt;<a class=" link-mailto" href="mailto:smontagu@example.org" rel="freelink">smontagu@example.org</a>&gt; - imported patch 435856
           | | 
           | o  6ee23de41631 - Phil Ringnalda &lt;<a class=" link-mailto" href="mailto:philringnalda@example.com" rel="freelink">philringnalda@example.com</a>&gt; - Bug 438526 - Opening links w
           | | 
           | o  22baa05d0e8a - Robert O'Callahan &lt;<a class=" link-mailto" href="mailto:robert@example.org" rel="freelink">robert@example.org</a>&gt; - Remove DOM testcase from exclusi
           | | 
           | o  c1aec2094f7e - Robert Longson &lt;<a class=" link-mailto" href="mailto:longsonr@example.com" rel="freelink">longsonr@example.com</a>&gt; - Bug 437448. New-style nsSVGString
           | | 
           | o  306726089e22 - Robert Longson &lt;<a class=" link-mailto" href="mailto:longsonr@example.com" rel="freelink">longsonr@example.com</a>&gt; - Bug 437448. New-style nsSVGString
           | | 
           | o  ba9b9a7c52a5 - Robert Longson &lt;<a class=" link-mailto" href="mailto:longsonr@example.com" rel="freelink">longsonr@example.com</a>&gt; - Bug 437448. New-style nsSVGString
           |/
           o  f8f4360bf155 - Robert O'Callahan &lt;<a class=" link-mailto" href="mailto:robert@example.org" rel="freelink">robert@example.org</a>&gt; - Bug 421436. Remove hack that gives
           |
           ⋮ (the past)
</pre>
<p>Your backout changeset is based on an old revision. It doesn't contain more recent changes.</p>
<p>Handle this like any other merge. If you've never done a merge before, get help. (It could be trivial or it could be a huge headache. There's plenty about merging elsewhere in this FAQ.)</p>
<h2 name="Help">Help</h2>
<h3 name="Help.2C_I_can.27t_push.21">Help, I can't push!</h3>
<p>If you're trying to push, and you can't, first try this:</p>
<pre class="eval">$$$$ ssh hg.mozilla.org
</pre>
<p>If you see output like:</p>
<pre class="eval">Permission denied (publickey,gssapi-with-mic).
</pre>
<p>it may have the following reasons:</p>
<ul> <li>you need to <a href="#How_do_I_check_stuff_in.3F">configure your username correctly</a></li> <li>you don't have the correct private key in ~/.ssh</li> <li>you don't have an hg.mozilla.org account. (If you should have one, <a class="link-https" href="https://bugzilla.mozilla.org/enter_bug.cgi?product=mozilla.org">file a bug</a> in mozilla.org:Server Operations.)</li>
</ul>
<p>If you see output like:</p>
<pre class="eval">You are not allowed to use this system, go away!
</pre>
<p>then you need to <a class="link-https" href="https://bugzilla.mozilla.org/enter_bug.cgi?product=mozilla.org">file a bug</a> in mozilla.org:Server Operations.</p>
<p>You should expect the ssh command to disconnect you immediately, since you're not supposed to have shell access. It may give the output:</p>
<pre class="eval">Could not chdir to home directory : No such file or directory
</pre>
<p>which is harmless (although some people see it and some people don't).</p>
<p>If you see output like:</p>
<pre class="eval">ssl required
</pre>
<p>then you need to <a href="#How_do_I_check_stuff_in.3F">configure your default-push correctly</a>.</p>
<h2 name="Things_that_have_changed">Things that have changed</h2>
<ul> <li>Bonsai is replaced by the <a class="external" href="http://hg.mozilla.org/mozilla-central/">Hg web viewer</a>. This lacks some bonsai features that would be nice, including mark, line-number anchors, and graphs. There are some terminology differences:</li>
</ul>
<p>bonsai blame == hg annotate<br>
bonsai log == hg revisions<br>
also you can browse the repository using the "manifest" link.</p>
<ul> <li>MXR for mozilla-central is <a class="external" href="http://mxr.mozilla.org/mozilla-central/">now available</a>.</li>
</ul>
<ul> <li>There's no Bugzilla integration for Mercurial.</li>
</ul>
<ul> <li><a href="/en/Mercurial//Desired_Features" title="en/Mercurial//Desired_Features">Mercurial/Desired Features</a></li>
</ul>
<p>{{ languages( { "es": "es/FAQ_de_Mercurial" } ) }}</p>
Revert to this revision