Mercurial is a source-code management tool which allows users to keep track of changes to the source code locally and share their changes with others. It is used for the development of Firefox.
Installing and configuring Mercurial
See Installing Mercurial.
Checking out a source tree
There are multiple hg repositories hosted at mozilla.org, see https://hg.mozilla.org/ for the full list.
mozilla-central (main development tree)
Most developers write patches against the mozilla-central tree.
Clone mozilla-central to get a local copy of the repository and then cd into it:
# This may take a while... hg clone https://hg.mozilla.org/mozilla-central/ firefox cd firefox
Latest successful build
The latest committed changes in your checkout may not build successfully. You may want to get the source code that has passed the automatic tests.
mozilla-inbound (used for landing your patches)
Most developers also maintain a clone of mozilla-inbound, which they use for landing their patches. You probably want to develop on top of mozilla-central, which tends to be more stable, but you should use mozilla-inbound when your patches are ready to land. See this page for how checking code into mozilla-inbound works.
hg clone https://hg.mozilla.org/integration/mozilla-inbound/ inbound cd inbound
mozilla-aurora (second-stage development tree)
When patches are considered ready for broader testing, they get branched onto
mozilla-aurora. This code, while more complete (and, in theory, stable) than mozilla-central, is not yet beta-quality. If you want to build off this branch, you can clone the repository as follows:
# Pull the Mozilla source to the folder aurora-src/ - may take a while # as hundreds of megabytes of history is downloaded to .hg hg clone https://hg.mozilla.org/releases/mozilla-aurora/ aurora cd aurora
mozilla-beta (prerelease development tree)
When a new release of Firefox enters beta testing, the code is branched into
mozilla-beta. This code represents the expected next release of the Firefox browser, and should be pretty stable. If you want to build off this branch, you can clone the repository as follows:
# Pull the Mozilla source to the folder beta-src/ - may take a while # as hundreds of megabytes of history is downloaded to .hg hg clone https://hg.mozilla.org/releases/mozilla-beta/ beta cd beta
mozilla-release (release tree)
To get the source repository for the current release of Firefox, do the following:
hg clone https://hg.mozilla.org/releases/mozilla-release release cd release
See Comm-central source code (Mercurial) for further information on pulling and building with
If you are creating a new localization based on an already-localized version of a Mozilla project, you will be interested in cloning this code. Code for all l10n projects lives in l10n-central and is organized (in most cases) by the locale's two character ISO code. When cloning, use the same ISO code to name the local directory that will store it. To get this code, do the following:
# Pull the Mozilla source to the folder src/ - may take a while # as hundreds of megabytes of history is downloaded to .hg hg clone https://hg.mozilla.org/l10n-central/your-ISO-code yourISOcode cd yourISOcode
See Mercurial bundles for information about downloading a single large file instead of using "hg clone".
Using Bookmarks to Manage Multiple Repositories from a Single Clone
This workflow is intended for people familar with Mercurial and Mozilla development. It is not recommended for first-time contributors.
It's possible to interact with Mozilla's multiple Mercurial repositories from a unified Mercurial repository using Mercurial's bookmarks feature.
To set up a unified Mercurial repository, the first step is to create a new, empty repository:
hg init mozilla
Next, edit the
.hg/hgrc file in that repository to contain the following:
[paths] central = https://hg.mozilla.org/mozilla-central central-push = ssh://hg.mozilla.org/mozilla-central inbound = https://hg.mozilla.org/integration/mozilla-inbound inbound-push = ssh://hg.mozilla.org/integration/mozilla-inbound aurora = https://hg.mozilla.org/releases/mozilla-aurora aurora-push = ssh://hg.mozilla.org/releases/mozilla-aurora beta = https://hg.mozilla.org/releases/mozilla-beta beta-push = ssh://hg.mozilla.org/releases/mozilla-beta release = http://hg.mozilla.org/releases/mozilla-release
What we've done here is defined the main Mozilla repositories under specific names.
Now, we're going to pull the information from each repository into our unified repository. Because of the way Mercurial internally stores data, it is recommended to pull from the repositories for older releases and work our way up to the newest.
hg pull release hg pull beta hg pull aurora hg pull central hg pull inbound
Now, you have all the information from all of these repositories in your local repository!
The next step is to create bookmarks for the main head of each repository. You'll use the hg identify command to look up the newest revision for each repository then create a bookmark for that revision.
hg bookmark -r `hg identify -r default central` central hg bookmark -r `hg identify -r default inbound` inbound hg bookmark -raurora hg bookmark -r beta hg bookmark -r `hg identify -r default release` release
Once you've created a bookmark, you can update the local tree to that bookmark. For example:
hg up inbound hg up central hg up beta
When you want to pull down the most recent changes for a tree, you simply update to that bookmark then pull down that repository. e.g.
hg up inbound hg pull -u inbound hg up central hg pull -u central
Pushing changes is similar, but is a little more complicated:
# Push the revision specified by the "inbound" bookmark to the repository "inbound-push" hg push -r inbound inbound-push
Please note that a bare
hg push <repo> will attempt to push all local changesets to the remote repository. This is not what you want. The server-side push hooks should prevent this push because they create new heads.
If you get into trouble and accidentally modify a bookmark to something it shouldn't be, you can forcefully reset the bookmark:
hg bookmark -f `hg identify -r default central` central hg up central
Once you understand what's going on behind the scenes, you may want to define some aliases to make managing the bookmarks and repositories easier. For example:
[alias] pulltree = !$HG pull $1 && hg bookmark -f -r `$HG identify -r default $1` $1 pushtree = push -r $1 $1-push pullproject = !$HG pull https://hg.mozilla.org/projects/$1 && hg bookmark -f -r `$HG identify -r default https://hg.mozilla.org/projects/$1` $1 pushproject = push -r $1 ssh://hg.mozilla.org/projects/$1 pullall = !$HG pulltree release && $HG pulltree beta && $HG pulltree aurora && $HG pulltree central && $HG pulltree inbound
Pull changesets from an individual named tree and update the bookmark that tracks that tree. e.g.
hg pulltree central.
This is the opposite of
pulltree. It pushes the changesets for the local tracking bookmark to a remote of the same name. e.g.
hg pushtree inbound.
Pull changesets from a named project branch from the
/projects/repository collection. e.g. elm.
Push changesets to a
This is a convenience method to pull all trees. It is implemented in terms of
These aliases rely on the names of the repositories and bookmarks matching. If you didn't follow the directions above exactly as written, they likely won't work.
By default with no configuration a similar-to-release build is done. If you wish you can configure the build using a
.mozconfig file and
make -f client.mk. Different OSs have different prerequisites for a successful build, please refer to the build documentation to verify they are available on your build machine.
- The Mercurial page has information about creating diffs, committing changes, and publishing shared repositories.