firefoxtree Extension

The firefoxtree Mercurial extension enhances the interaction with Firefox repositories.

Background on Multiple Repositories

Firefox developers typically interact with multiple repositories. There is the canonical head of Firefox development, mozilla-central. There are landing repositories such as mozilla-inbound and fx-team. Then there are release repositories like mozilla-aurora, mozilla-beta, and mozilla-release.

All of these repositories share the same initial commit and thus are one logical repository. However, for historical and continuity reasons, the separate topological heads of this conceptual single repository are all stored in separate repositories on Mozilla’s servers.

Consolidating the Repositories Locally

Traditionally, Mozilla developers maintain separate clones of each repository. There is thus a one to one mapping between local and remote repositories. For example, you may have separate mozilla-central and mozilla-inbound directories/clones to track the different upstream repositories. This practice is grossly inefficient. The shared repository data is fetched and stored multiple times. This creates more load for the server, occupies more space on disk, and adds overhead to common tasks such as rebasing from central to inbound.

The firefoxtree extension allows you to easily combine the separate remote repositories into a local, single, unified repository.

When you hg pull from a known Firefox repository, firefoxtree will automatically create a local-only label corresponding to the name of the remote repository. These labels will manifest as tags. For example:

$ hg pull https://hg.mozilla.org/mozilla-central
pulling from https://hg.mozilla.org/mozilla-central
searching for changes
adding changesets
adding manifests
adding file changes
added 130 changesets with 651 changes to 329 files
(run 'hg update' to get a working copy)

$ hg log -r tip
changeset:   248552:d380166816dd
tag:         central
tag:         tip
user:        ffxbld
date:        Sat Nov 08 03:20:23 2014 -0800
summary:     No bug, Automated blocklist update from host bld-linux64-spot-144 - a=blocklist-update

You can see from the output of hg log that changeset d380166816dd has the central tag associated with it.

The following example demonstrates how to pull various Firefox repositories into a single local repository and then how to navigate between commits.:

$ hg pull https://hg.mozilla.org/integration/mozilla-inbound
pulling from https://hg.mozilla.org/integration/mozilla-inbound
searching for changes
adding changesets
adding manifests
adding file changes
added 34 changesets with 140 changes to 113 files (+1 heads)
(run 'hg heads .' to see heads, 'hg merge' to merge)

$ hg pull https://hg.mozilla.org/integration/b2g-inbound
pulling from https://hg.mozilla.org/integration/b2g-inbound
searching for changes
adding changesets
adding manifests
adding file changes
added 21 changesets with 119 changes to 13 files (+1 heads)
(run 'hg heads .' to see heads, 'hg merge' to merge)

$ hg up central
327 files updated, 0 files merged, 10 files removed, 0 files unresolved

$ hg log -r .
changeset:   248552:d380166816dd
tag:         central
tag:         tip
user:        ffxbld
date:        Sat Nov 08 03:20:23 2014 -0800
summary:     No bug, Automated blocklist update from host bld-linux64-spot-144 - a=blocklist-update

$ hg up inbound
118 files updated, 0 files merged, 2 files removed, 0 files unresolved

$ hg log -r .
changeset:   248586:e021487d1297
tag:         inbound
user:        Connor <cojojennings@gmail.com>
date:        Wed Oct 29 23:58:03 2014 -0400
summary:     Bug 575094 - Modify how prefservice is accessed so that it's from the parent process and not from the child process. Also re-enable test_bug528292_wrap.js. r=jdm

Tip

If you are familiar with Git, it may help to think of these repository labels as remote refs.

To view a summary of which repositories are on which changesets, run hg fxheads:

$ hg fxheads
248607:a7a2bacecce7 b2ginbound tip Bumping manifests a=b2g-bump
248552:d380166816dd central No bug, Automated blocklist update from host bld-linux64-spot-144 - a=blocklist-update
246125:c742dcb56135 fx-team Bug 1088729 - Only allow http(s) directory links and https/data images [r=adw]
248586:e021487d1297 inbound Bug 575094 - Modify how prefservice is accessed so that it's from the parent process and not from the child process. Also re-enable test_bug528292_wrap.js. r=jdm

Tip

The output of hg fxheads is only current from the last time you pulled from each repository. Given the frequency of pushes to the Firefox repositories, at least one of your labels will likely be out of date.

Pre-defined Repository Paths

Typically, if you are pulling from multiple remotes, you need to define the names and URLs of those remotes in the [paths] section of the repository’s .hg/hgrc file. The names and URLs of Firefox repositories are well-known, so firefoxtree does this for you.

Simply type hg pull <tree> to pull from a known Firefox repository. For example:

$ hg pull central
$ hg pull inbound

Or type hg push <tree> to push to a Firefox repository.:

$ hg push inbound
$ hg push aurora

Tip

The registered name aliases should be intuitive. Try a name of a popular Firefox repository. It should just work. If you get stumped or want to see the full list of names, read the source.

The Special fxtrees Path

The fxtrees path is special. If you hg pull fxtrees, firefoxtree will pull from all Firefox repositories that you have previously pulled from.

Typically, developers only care about a subset of all the Firefox repositories. hg pull fxtrees provides a convenient mechanism to only pull the repositories you have previously expressed an interest in interacting with.

The review Path

Using review as a path will automatically utilize the MozReview code review repository.

Other Special Paths

There are some special paths that expand to multiple repositories. If you run hg pull with one of these paths, firefoxtree will iterate through each of these repositories and pull from all of them. These special paths include:

integration
Pull from all integration/landing repositories (inbound, fx-team, b2g-inbound)
releases
Pull from all repositories that Firefox is released from (central, aurora, beta, release, esr, etc)

Safer Push Defaults

The default behavior of hg push is to want to transfer all non-remote changesets to the remote. In other words, if you have pulled mozilla-central and mozilla-aurora into the same repository and you hg push ssh://hg.mozilla.org/mozilla-central, Mercurial will want to transfer all of mozilla-aurora’s changesets to central!

The way you are supposed to do this is to always pass a --rev or -r argument to hg push to tell Mercurial exactly what changesets to push. Commonly, you want to push the working copy’s commit, so the command to use would be hg push -r . <remote>.

Since hg push -r . is almost always what is wanted when pushing to a Firefox repository, firefoxtree automatically changes hg push to behave like hg push -r . when pushing to a Firefox repository.

Working with Unified Repositories and Repository Labels

Astute readers may have noticed that Mercurial is reporting the repository labels as tags. However, they don’t behave like tags. The .hgtags file is not updated and hg push won’t transfer them. Under the hood, the extension is using an extension-only feature of Mercurial to supplement the tags list. The labels are being reported as tags, but have almost nothing to do with actual tags.

The repository labels can only be modified by firefoxtree. Furthermore, they are only modified when running hg pull. Unlike bookmarks or branches, user actions such as committing will not advance the labels.