Installing and Configuring Extensions¶
A vanilla install of Mercurial does not have many features. This is an intentional choice by Mercurial to keep the base install simple and free of foot guns.
To install an extension, you’ll need to add a line to your Mercurial configuration file.
As a user, you care about the following configuration files:
- Your global hgrc
- A per-repository hgrc
Your user-global configuration file is
~/.hgrc. Settings in this
file apply to all
hg commands you perform everywhere on your system
(for your current user).
Each repository that you clone or initialize has an optional
.hg/hgrc file that provides repository-specific configurations.
Mercurial starts by loading and applying settings from global configuration files and then overlays configurations from each lesser-scoped files.
To learn more about Mercurial configuration files, run
To install an extension, you add a line under the
section of a config file like the following:
This is saying activate the **foo* extension whose code is present at path/to/extension*.
Core Extensions That Almost Everyone Wants¶
Mercurial ships with a number of built-in extensions. Of these, every user will almost always want to install the following extensions:
- This extension adds colorized output to commands, making output easier to read.
- Monitor the filesystem for changes using so operations querying filesystem state complete faster.
fsmonitor is highly recommended when interacting with the Firefox repository. It will make Mercurial commands faster.
- Enable command output to go to a pager (such as less).
Show progress bars during long-running operations.
progresswas moved to Mercurial’s core and is enabled by default in Mercurial 3.5+.)
Since core extensions are bundled with Mercurial, they have a special syntax that makes them easier to install:
[extensions] color= pager=
Core Extensions to Perform History Rewriting¶
Out of the box, Mercurial only allows commits operations to be additive. If you make a mistake, the solution is to create a new commit that fixes it. You can’t rewrite old commits. You can’t change the order of existing commits. You can’t change the shape of the DAG of the commits.
These operations all have something in common: they rewrite history.
Mercurial doesn’t allow history rewriting by default because it is a major foot gun for people new to version control. A potential side-effect of history rewriting is data loss or confusion due to loss of state. Mercurial believes that these risks should be opt-in and has thus shipped without any history rewriting features enabled by default.
Mercurial ships with a number of built-in extensions that enable history rewriting:
hg histeditcommand, which brings up a text editor listing commits, allowing you to change order and specify actions to perform.
The functionality is roughly equivalent to
git rebase -i.
- Enables the
hg rebasecommand, which allows you to splice commits across different chains in the DAG.
- Enables you to delete changesets completely.
Core Extensions to Enable Different Workflows¶
Mercurial ships with some extensions that enable alternate workflows. These include:
- Enables uncommitted work to be saved to a standalone file without being committed to the repository.
3rd Party Extensions You Should Highly Consider¶
chg is a C wrapper for the
command. Typically, when you type
hg, a new Python process is created,
Mercurial is loaded, and your requested command runs and the process exits.
chg, a Mercurial command server background process is created
that runs Mercurial. When you type
chg, a C program connects to that
background process and executes Mercurial commands.
chg can drastically speed up Mercurial. This is because the overhead
for launching a new Python process is high (often over 50ms) and the
overhead for loading Mercurial state into that process can also be high.
chg, you may this cost once and all subsequent commands
effectively eliminate the Python and Mercurial startup overhead. For
$ time hg --version real 0m0.118s user 0m0.100s sys 0m0.015s $ time chg --version real 0m0.012s user 0m0.000s sys 0m0.004s $ time hg export real 0m0.137s user 0m0.093s sys 0m0.042s $ time chg export real 0m0.034s user 0m0.000s sys 0m0.004s
Here, we see ~100ms wall time improvement with chg activated. That may not sound likea lot, but you will notice.
Additional 3rd Party Extensions to Consider¶
The evolve extension opens up new workflows that harness Mercurial’s ability to record how changesets evolve over time.
Typically, when history is rewritten, new commits are created and the old
ones are discarded. With the
evolve extension enabled, Mercurial intsead
hides the old commits and writes metadata holding the relationship between
old and new commits. This metadata can be transferred between clients,
allowing clients to make intelligent decisions about how to recover from
rewritten history. For example, if a force push is performed, a client
will now exactly what rebase to perform to mimic what was done elsewhere.
evolve extension also enables useful Mercurial commands such as
hg next, and
hg amend (which is a shortcut for
hg commit --amend).
Mozilla Centric Extensions¶
In addition to the many extensions in this repository, you should also consider the following.
The trychooser extension helps with the process of submitting to Try (Mozilla’s special repository that kicks off automation build and test jobs from submitted code).
In addition to helping you select a trychooser syntax, this extension also manages the temporary commit required to hold that syntax. This means less typing to get your repository in order to send things to Try.