Set up the environment for Mercurial

IMPORTANT: This configuration has to be done only once on the computer. After that you will simply need to keep Mercurial up to date (a new version is released every month).

Mercurial

Most of the work needs to be done in Mercurial, so you need to install if first. An alternative way to install it on macOS is via homebrew with brew install hg (brew upgrade hg to update it later).

To check if Mercurial is available and up to date, run in the terminal hg --version, the output should look like this:

$ hg --version
Mercurial Distributed SCM (version 4.0.1)
(see https://mercurial-scm.org for more information)

Copyright (C) 2005-2016 Matt Mackall and others
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

Unless you’re familiar with vi, you also want to setup nano as the default editor in the system.

$ export EDITOR=/usr/bin/nano

Mercurial configuration

Mercurial’s configuration is stored in a hidden file called .hgrc inside your user folder (~/.hgrc). You will need to create it if it’s not available on the system.

It’s divided into sections, with section names between square parentheses. For example:

[ui]
username = something@example.com

Set up MozPhab for Phabricator

Detailed instructions and explanations are available in the official documentation.

You also need to create an account on Phabricator and log in.

The configuration will be completed after cloning mozilla-unified.

Cloning and updating mozilla-unified

Since searchplugins are stored in mozilla-central, you will also need a clone of it on your computer. Using the mozilla-unified repository repository is a better solution, especially if you need to work on more than just mozilla-central.

$ cd ~/mozilla/mercurial/
$ hg clone https://hg.mozilla.org/mozilla-unified

To update the existing repository:

$ cd ~/mozilla/mercurial/mozilla-unified
$ hg pull -u
$ hg up central

The last command makes sure you’re working against central (to be more precise, it moves you to the central bookmark).

Now you can complete the setup for MozPhab. Follow the instructions on screen to complete, it will require you to connect to Phabricator and generate an API key to copy in the terminal:

$ cd ~/mozilla/mercurial/mozilla-unified
$ moz-phab install-certificate

Mercurial configuration

Mercurial configuration is stored in the .hgrc file in the user’s home directory.

Useful extensions are Mercurial Queues Extension (queues), color (colorize output, for example diffs) and purge (to remove untracked files from the repository). If the .hgrc file doesn’t have an [extensions] section create one and add the following lines:

[extensions]
mq =
color =
purge =

Some aliases are also useful to work with bookmarks:

[alias]
shortlog = log --template "{node|short} | {date|isodatesec} | {author|user}: {desc|strip|firstline}\n"
wip = log --graph --rev=wip --template=wip

[revsetalias]
wip = (parents(not public()) or not public() or . or (head() and branch(default))) and (not obsolete() or orphan()^) and not closed()
# If firefoxtree is enabled
# wip = (parents(not public()) or not public() or . or (head() and branch(default))) and (not obsolete() or orphan()^) and not closed() and not (fxheads() - date(-90))

[templates]
wip = '{label("log.branch", branches)} {label("changeset.{phase}", rev)}{label("changeset.{phase}", ":")}{label("changeset.{phase}", short(node))} {label("grep.user", author|user)}{label("log.tag", if(tags," {tags}"))}{label("log.tag", if(fxheads," {fxheads}"))} {label("log.bookmark", if(bookmarks," {bookmarks}"))}\n{label(ifcontains(rev, revset("."), "desc.here"),desc|firstline)}'

Text editor

The suggestion is to use Visual Studio Code.

If you don’t like to use nano to edit commit messages, you can also use a graphical editor. A possible alternative on macOS is to use TextMate: after installing it, open Preferences and install the Shell support (Terminal tab), then add a editor preference to .hgrc.

[ui]
username = YOUR NAME <YOUR EMAIL>
ignore.other = ~/.hgignore
editor = mate -w

You can also use Visual Studio Code, but it’s definitely slower.

[ui]
username = YOUR NAME <YOUR EMAIL>
ignore.other = ~/.hgignore
editor = code --wait

In general, in order to be able to use it for commit messages, you’ll need a text editor available from the command line, and with a wait option.