Using Mercurial

  • Revision slug: Mercurial_FAQ
  • Revision title: Using Mercurial
  • Revision id: 11258
  • Created:
  • Creator: Jonathan_Watt
  • Is current revision? No
  • Comment 32 words added

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.
  • 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.
  • With Mercurial, a complete, fully armed and operational clone of the entire Mozilla repository is on your local hard drive. Even when you are offline, you can use hg log for a list of revisions to a file or hg blame to find out who is responsible for a line of code.
  • You can do work locally and check it in (hg commit) without affecting anybody else. To push changes upstream, use hg push after committing.
  • Mercurial makes branching quick and easy and keeps merging pretty much sane. (See Publishing Mercurial Clones.)
  • 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.

  • Mercurial has many options. For example, it can be configured to launch an external, interactive merge program instead of leaving conflict markers in the file. (If you like conflict markers, stick with "internal:merge".) DiffMerge is probably the most intuitive/least intimidating graphical merge program for anyone new to distributed version control and three way merging, and it's cross-platform.
  • 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?

See Installing 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') }}.

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 = internal:merge

[defaults]
commit = -v

[diff]
git = 1
showfunc = 1
unified = 8

On Windows, these settings can be added to C:\Program Files\Mercurial\Mercurial.ini, or, if you'd like per-user settings, $HOME\.hgrc or $HOME\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

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 three things you can do.

Using hg rebase (Mercurial 1.1 and above)

This is the simplest and easiest way to deal with the problem. You can rebase your local changesets (including mq patches) on top of the tip using the rebase extension. To do this, simply enable the extension by adding this to the following section of your .hgrc:

[extensions]
hgext.rebase =

Now, type hg pull --rebase to pull and rebase your local changesets at the same time. More details and options can be found at the Mercurial wiki.

If you have conflicting changes, you'll be thrown into your preferred merge tool.

As of Mercurial 1.1, rebasing (especially with mq patches) might lose rename data; this is a known bug that has been fixed in Mercurial 1.3. 

Using hg merge

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 leaves a merge commit in the log, which some people find annoying, so it's usually better to use rebase instead.

Using Mercurial queues

{{ 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.") }}

This is deprecated in favor of using hg rebase, but one more 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.

The disadvantage here is that if there are merge conflicts, you're going to have to deal with a bunch of .rej files.

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
#for Mercurial 1.1 use:
#qdiff=-U 8 -p
[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 hg export and 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.  You may want to add showfunc=true here to get diffs that show the function being changed in each hunk, and you may want to add unified=8 to make all diffs (including the internal ones mq uses) have 8 lines of context. Note that this may increase the risk of mq patches failing to apply!

How do I get a diff -w?

There is a known issue where hg diff -w 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 -r -N -p -U 8

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.

How do I generate a bundle?

Sometimes the tree will be under sheriff control, and they will specifically ask for a bundle.  If you don't have sufficient rights to push to mozilla-central, you might also generate bundles and attach them to bugs when you add checkin-needed to a bug after it has the necessary reviews and approval.

Creating a bundle is quite simple.  Once you have your changes all done, commit them to your local repository.  You can also commit more than one changeset.  Once you have everything committed, instead of pushing you'll run hg bundle:

hg bundle outputfile.hg

By default, hg bundle will bundle everything that hg outgoing would display (and what you would push with hg push).  You can limit how far forward you want to bundle as well by specifying a revision with -r.  That will take all changes up until that revision.

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.
  • MXR for mozilla-central is now available.
  • See also Mercurial/Desired Features

{{ 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> <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> <li>With Mercurial, a complete, fully armed and operational <em>clone</em> of the entire Mozilla repository is on your local hard drive. Even when you are offline, you can use <code>hg log</code> for a list of revisions to a file or <code>hg blame</code> to find out who is responsible for a line of code.</li> <li>You can do work locally and check it in (<code>hg commit</code>) without affecting anybody else. To push changes upstream, use <code>hg push</code> after committing.</li> <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> <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> <li>Mercurial has many options. For example, it can be configured to launch an external, interactive <a class="external" href="http://www.selenic.com/mercurial/wiki/index.cgi/MergeProgram">merge program</a> instead of leaving conflict markers in the file. (If you like conflict markers, stick with "internal:merge".) <a class="external" href="http://mercurial.selenic.com/wiki/DiffMerge" title="http://mercurial.selenic.com/wiki/DiffMerge">DiffMerge</a> is probably the most intuitive/least intimidating graphical merge program for anyone new to distributed version control and three way merging, and it's cross-platform.</li> <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>See <a class="internal" href="/en/Installing_Mercurial" title="En/Installing Mercurial">Installing Mercurial</a>.</p>
<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="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 = internal:merge

[defaults]
commit = -v

[diff]
git = 1
showfunc = 1
unified = 8</pre>
<p>On Windows, these settings can be added to <code>C:\Program Files\Mercurial\Mercurial.ini</code>, or, if you'd like per-user settings, <code>$HOME\.hgrc </code>or <code>$HOME\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>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/Developer_Guide/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> <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> <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> <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>
<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 three things you can do.</p>
<h4>Using <code>hg rebase</code> (Mercurial 1.1 and above)</h4>
<p>This is the simplest and easiest way to deal with the problem. You can rebase your local changesets (including mq patches) on top of the tip using the <a class="external" href="http://www.selenic.com/mercurial/wiki/index.cgi/RebaseExtension" title="http://www.selenic.com/mercurial/wiki/index.cgi/RebaseExtension">rebase extension</a>. To do this, simply enable the extension by adding this to the following section of your <code>.hgrc</code>:</p>
<pre class="eval">[extensions]
hgext.rebase =
</pre>
<p>Now, type <code>hg pull --rebase <span style="font-family: sans-serif;">to pull and rebase your local changesets at the same time.</span></code> More details and options can be found at the <a class="external" href="http://www.selenic.com/mercurial/wiki/index.cgi/RebaseProject" title="http://www.selenic.com/mercurial/wiki/index.cgi/RebaseProject">Mercurial wiki</a>.</p>
<p>If you have conflicting changes, you'll be thrown into your preferred merge tool.</p>
<div class="note">As of Mercurial 1.1, rebasing (especially with mq patches) might lose rename data; this is a <a class="external" href="http://www.selenic.com/mercurial/bts/issue1423" title="http://www.selenic.com/mercurial/bts/issue1423">known bug</a> that has been fixed in Mercurial 1.3. </div>
<h4>Using <code>hg merge</code></h4>
<p>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 leaves a merge commit in the log, which some people find annoying, so it's usually better to use rebase instead.</p>
<h4>Using Mercurial queues</h4>
<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>This is deprecated in favor of using <code>hg rebase</code>, but one more thing you can do is to import the commit into <a class="external" href="http://www.selenic.com/mercurial/wiki/index.cgi/MqExtension" style="">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>
<p>The disadvantage here is that if there are merge conflicts, you're going to have to deal with a bunch of .rej files.</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
#for Mercurial 1.1 use:
#qdiff=-U 8 -p</pre>
<pre class="eval">[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 <code>hg export</code> and 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.  You may want to add <code>showfunc=true</code> here to get diffs that show the function being changed in each hunk, and you may want to add <code>unified=8</code> to make all diffs (including the internal ones <a class="external" href="http://www.selenic.com/mercurial/wiki/index.cgi/MqExtension" style="">mq</a> uses) have 8 lines of context. Note that this may increase the risk of mq patches failing to apply!</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> where <code>hg diff -w</code> 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 -r -N -p -U 8
</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>
<h3>How do I generate a bundle?</h3>
<p>Sometimes the tree will be under sheriff control, and they will specifically ask for a bundle.  If you don't have sufficient rights to push to mozilla-central, you might also generate bundles and attach them to bugs when you add checkin-needed to a bug after it has the necessary reviews and approval.</p>
<p>Creating a bundle is quite simple.  Once you have your changes all done, commit them to your local repository.  You can also commit more than one changeset.  Once you have everything committed, instead of pushing you'll run <code>hg bundle</code>:</p>
<pre>hg bundle outputfile.hg
</pre>
<p>By default, <code>hg bundle</code> will bundle everything that <code>hg outgoing</code> would display (and what you would push with <code>hg push</code>).  You can limit how far forward you want to bundle as well by specifying a revision with <code>-r</code>.  That will take all changes up until that revision.</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: <ul> <li>bonsai blame == hg annotate</li> <li>bonsai log == hg revisions</li> <li>also you can browse the repository using the "manifest" link.</li> </ul> </li> <li>MXR for mozilla-central is <a class="external" href="http://mxr.mozilla.org/mozilla-central/">now available</a>.</li> <li>See also <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