.. _hgmozilla_installing: ==================== Installing Mercurial ==================== Having a modern Mercurial installed is important. Features, bug fixes, and performance enhancements are always being added to Mercurial. Staying up to date on releases is important to getting the most out of your tools. .. note:: Mercurial has a strong commitment to backwards compatibility. If you are scared that upgrading will break workflows or command behavior, don't be. It is very rare for Mercurial to intentionally break backwards compatibility. Recommended Versions ==================== Mozilla recommends running the latest stable release of Mercurial. The latest stable release is always listed at `https://www.mercurial-scm.org/ `_. **As of October 2018, the latest stable release is 4.7.2.** .. danger:: Mercurial versions before 3.7.3 have known vulnerabilities that can lead to arbitrary code execution when pulling from repositories. Mercurial versions before 4.4.1 have known vulnerabilities that can result in arbitrary client-side code execution when processing subrepositories. Mercurial versions before 4.6.1 have possible vulnerabilities that could result in arbitrary client-side code execution when pulling from repositories. Mercurial versions before 4.7.2 have a possible out-of-bounds memory access that could result in security issues. Version 4.7.2 or newer should always be used. Mercurial makes a major *X.Y* release every three months, typically around the first of the month. Release months are February, May, August, and November. A *X.Y.Z* point release is performed each month after or as needed (if a severe issue is encountered). If you are conservative about software updates, it is OK to wait to upgrade until the *X.Y.1* point release following a major version bump. Installing on Windows ===================== If you are a Firefox developer, you should install Mercurial indirectly through `MozillaBuild `_. Mercurial can be upgraded within MozillaBuild by running ``pip install --upgrade Mercurial``. If you are not a Firefox developer, download a Windows installer `direct from the Mercurial project `_. Installing on OS X ================== Mercurial is not installed on OS X by default. You will need to install it from a package manager or install it from source. mach bootstrap -------------- If you have a clone of a Firefox repository, simply run ``mach bootstrap`` to install/upgrade Mercurial. Keep in mind this will install all packages required for Firefox development. If this is not wanted, follow a set of instructions below. Homebrew -------- Homebrew typically keeps their Mercurial package up to date. Install Mercurial through Homebrew by running:: $ brew install mercurial You may want to run ``brew update`` first to ensure your package database is up to date. MacPorts -------- MacPorts typically keeps their Mercurial package up to date. Install through MacPorts by running:: $ port install mercurial From Source ----------- See the section below about how to install Mercurial from source. Installing on Linux, BSD, and other UNIX-style OSs ================================================== The instructions for installing Mercurial on many popular distributions are available on `Mercurial's web site `_. However, many distros don't keep their Mercurial package reasonably current. You often need to perform a source install. Installing from Pip =================== Mercurial source packages can be installed via ``pip`` - Python's preferred package management tool. Installing Mercurial via pip is simple:: $ pip install Mercurial To upgrade Mercurial:: $ pip install --upgrade Mercurial By default, ``pip install`` may try to write to ``/usr/local`` or ``/usr/lib`` or other parts of your system that require elevated permissions to write to. To perform an install into your user directory:: $ pip install --user Mercurial That *may* install Mercurial to a directory not in ``PATH``, such as ``~/.local/bin``. You may need to adjust your shell's startup file to add this directory to ``PATH``. To see exactly where it installs things in ``--user`` mode, run ``pip show Mercurial``. There will be a line like ``Location: /home/myuser/.local/lib/python2.7/site-packages``. The ``hg`` executable is likely in a ``bin`` directory at the same level of the ``lib/`` directory. Installing from Source ====================== Installing Mercurial from source is simple and should not be dismissed because it isn't coming from a package. Download a `source archive `_ from Mercurial. Alternatively, clone the Mercurial source code and check out the version you wish to install:: $ hg clone https://www.mercurial-scm.org/repo/hg $ cd hg $ hg up 4.7.2 Once you have the source code, run ``make`` to install Mercurial:: $ make install If you would like to install Mercurial to a custom prefix:: $ make install PREFIX=/usr/local $ make install PREFIX=/home/gps .. note:: Mercurial has some Python C extensions that make performance-critical parts of Mercurial significantly faster. You may need to install a system package such as ``python-dev`` to enable you to build Python C extensions. .. tip:: Are you concerned about a manual Mercurial install polluting your filesystem? Don't be. A Mercurial source install is fully self-contained. If you install to a prefix, you only need a reference to the ``PREFIX/bin/hg`` executable to run Mercurial. You can create a symlink to ``PREFIX/bin/hg`` anywhere in ``PATH`` and Mercurial should *just work*. Verifying Your Installation =========================== To verify Mercurial is installed properly and has a basic configuration in place, run:: $ hg debuginstall If it detects problems, correct them. If you have a clone of the Firefox repository, you are highly encouraged to run `mach vcs-setup` to launch an interactive wizard that will help you optimally configure Mercurial for use at Mozilla. Reasons to Upgrade ================== General Advice -------------- Mercurial releases tend to be faster and have fewer bugs than previous releases. These are compelling reasons to stay up to date. Avoid Mercurial versions older than 3.7.3 due to issues below. Security Issues --------------- Versions of Mercurial before 3.7.3 are vulnerable to multiple security issues that can lead to executing arbitrary code when cloning or pulling from repositories. Avoid versions older than 3.7.3! Cloning and Pulling Performance ------------------------------- Mercurial 4.1 introduced supported for compression data over the wire protocol with zstandard. This is substantially faster than zlib and can result in faster clones and pulls due to faster compression and fewer bytes transferred over the wire. Mercurial 3.6 contains a number of enhancements to performance of cloning and pull operations, especially on Windows. Clone times for mozilla-central on Windows can be several minutes faster with 3.6. Revset Performance ------------------ Mercurial 3.5 and 3.6 contained a number of performance improvements to revision sets. If you are a user of ``hg wip`` or ``hg smartlog``, these commands will likely be at least 4x faster on Mercurial 3.6. Revsets are used internally by Mercurial. So these improvements result in performance improvements for a hodgepodge of operations. Tags Cache Performance ---------------------- Mercurial 3.4 contains improvements to the tags cache that prevent it from frequently doing CPU-intensive computations in some workflows. .. important:: Users of evolve will have horrible performance due to the tags cache implementation in versions older than 3.4 and should upgrade to 3.4+. Performance Issues with Large Repositories ------------------------------------------ Mercurial 3.0 through 3.1.1 contained a significant performance regression that manifests when cloning or pulling tens of thousands of changesets. These versions of Mercurial should be avoided when interacting with large repositories, such as mozilla-central. Mercurial 3.3 introduced a class of performance regressions most likely encountered as part of running ``hg blame`` or ``hg graft``. The regressions are largely fixed in 3.4. CVE-2014-9390 ------------- Mercurial versions older than 3.2.3 should be avoided due to a security issue (CVE-2014-9390) impacting Windows and OS X users. Supporting Old Versions ----------------------- Mozilla has written a handful of Mercurial extensions. Supporting N versions of Mercurial is easier than supporting N+1 versions, especially as Mercurial's API is rapidly evolving. It is extra work to support old versions when new versions work just fine. Newer Wire Protocol ------------------- Mercurial 3.5 featured a new wire protocol that performs pushes and pulls more efficiently. Cloning from Pre-Generated Bundle Files --------------------------------------- Mercurial 3.6 supports transparently cloning from pre-generated bundle files. When you clone from hg.mozilla.org, many of the larger repositories will be served from a CDN. This results in a faster and more reliable clone. Mercurial 4.1 will download zstandard-compressed bundles from hg.mozilla.org by default. These are substantially smaller than gzip-based bundles.