Upgrading Mercurial
Notes on upgrading Mercurial.
Contents
1. Introduction
Mercurial is designed to be painless to upgrade. This means:
- existing repositories will continue to be usable
- existing configuration will continue to work
- existing usage patterns will continue to work
- existing automation based on Mercurial's command-line interface will continue to work
- new clients will interoperate with old servers
- new servers will interoperate with old clients
Any changes that break these rules will be listed in our upgrade notes and will generally be very minor.
Mercurial is continually subjected to a large suite of regression tests, so it is generally safe to test any version of Mercurial, including unreleased development versions.
There are two notable areas where you may encounter problems between major releases (ie 1.6 to 1.7):
- multiple client versions on a shared disk
- third-party or custom extensions and Python hooks
2. Multiple client versions on a shared disk
New clients, by default, will create new repositories with all current features enabled. If multiple users are using different client versions on a shared disk (ie NFS or Windows share), old clients may report "requirement not supported" when trying to read directly from these repositories. To avoid this issue, there are three approaches:
- only use old clients to create new repositories
use settings in the "format" section of 'hgrc' to disable new repository features
- use hg serve / hg pull to 'convert' new repositories back to the old format
3. Third-party or custom extensions and Python hooks
Unlike Mercurial's command line interface, Mercurial's internal interfaces may change significantly between major releases. This may require upgrading any third-party extensions you are using.
If you have custom extensions or hooks written in Python, you may need to modify them when upgrading to a new major release. See API changes for details.
4. Support and obsolescence
Because of our focus on painless backward-compatibility, we do not do continued maintenance on old releases. We encourage all users to upgrade to the latest major release when they encounter problems.
5. See also
Our upgrade notes list any possible compatibility issues
Downloads for latest versions
Our compatibility rules for new features
Recent API changes