|
|
Mercurial can be augmented with Rust extensions for speeding up certain
|
|
|
operations.
|
|
|
|
|
|
Word of Caution
|
|
|
===============
|
|
|
|
|
|
Using the Rust extension might result in the use of various repository formats
|
|
|
that are not supported by non-Rust mercurial. When using a Mercurial
|
|
|
without Rust support on the same repositories, you might need to downgrade your
|
|
|
repository formats and/or activate cripplingly slow paths for compatibility.
|
|
|
For details, see:
|
|
|
|
|
|
- :hg:`help config.format.use-persistent-nodemap`
|
|
|
- :hg:`help config.format.use-dirstate-v2`
|
|
|
|
|
|
In addition, while the tests are run with the Rust code, there might be
|
|
|
subtle undetected divergences from the historical non-Rust code. So keep
|
|
|
your eyes open and report any oddity. Rust is not considered a first class
|
|
|
citizen to the project yet.
|
|
|
|
|
|
Compatibility
|
|
|
=============
|
|
|
|
|
|
Though the Rust extensions are only tested by the project under Linux, users of
|
|
|
MacOS, FreeBSD and other UNIX-likes have been using the Rust extensions. Your
|
|
|
mileage may vary, but by all means do give us feedback or signal your interest
|
|
|
for better support.
|
|
|
|
|
|
For compatibility with non-Rust version of Mercurial check the previous "Word of
|
|
|
Caution" section.
|
|
|
|
|
|
No Rust extensions are available for Windows at this time.
|
|
|
|
|
|
Features
|
|
|
========
|
|
|
|
|
|
The following operations are sped up when using Rust:
|
|
|
|
|
|
- discovery of differences between repositories (pull/push)
|
|
|
- nodemap (see :hg:`help config.format.use-persistent-nodemap`)
|
|
|
- all commands using the dirstate (status, commit, diff, add, update, etc.)
|
|
|
- dirstate-v2 (see :hg:`help config.format.use-dirstate-v2`)
|
|
|
- iteration over ancestors in a graph
|
|
|
|
|
|
More features are in the works, and improvements on the above listed are still
|
|
|
in progress. For more experimental work see the "rhg" section.
|
|
|
|
|
|
Checking for Rust
|
|
|
=================
|
|
|
|
|
|
You may already have the Rust extensions depending on how you install
|
|
|
Mercurial::
|
|
|
|
|
|
$ hg debuginstall | grep -i rust
|
|
|
checking Rust extensions (installed)
|
|
|
checking module policy (rust+c-allow)
|
|
|
|
|
|
If those lines don't even exist, you're using an old version of `hg` which does
|
|
|
not have any Rust extensions yet.
|
|
|
|
|
|
Installing
|
|
|
==========
|
|
|
|
|
|
You will need `cargo` to be in your `$PATH`. See the "MSRV" section for which
|
|
|
version to use.
|
|
|
|
|
|
Using pip
|
|
|
---------
|
|
|
|
|
|
Users of `pip` can install the Rust extensions with the following command::
|
|
|
|
|
|
$ pip install mercurial \
|
|
|
--global-option \
|
|
|
--rust \
|
|
|
--no-use-pep517 \
|
|
|
--no-binary mercurial
|
|
|
|
|
|
`--no-use-pep517` is here to tell `pip` to preserve backwards compatibility with
|
|
|
the legacy `setup.py` system. Mercurial has not yet migrated its complex setup
|
|
|
to the new system, so we still need this to add compiled extensions.
|
|
|
|
|
|
`--no-binary` is there to tell pip to not use the pre-compiled wheels that are
|
|
|
missing rust support. This might take a couple of minutes because you're
|
|
|
compiling everything.
|
|
|
|
|
|
See the "Checking for Rust" section to see if the install succeeded.
|
|
|
|
|
|
From your distribution
|
|
|
----------------------
|
|
|
|
|
|
Some distributions are shipping Mercurial with Rust extensions enabled and
|
|
|
pre-compiled (meaning you won't have to install `cargo`), or allow you to
|
|
|
specify an install flag. Check with your specific distribution for how to do
|
|
|
that, or ask their team to add support for hg+Rust!
|
|
|
|
|
|
From source
|
|
|
-----------
|
|
|
|
|
|
Please refer to the `rust/README.rst` file in the Mercurial repository for
|
|
|
instructions on how to install from source.
|
|
|
|
|
|
MSRV
|
|
|
====
|
|
|
|
|
|
The minimum supported Rust version is defined in `rust/clippy.toml`.
|
|
|
The project's policy is to keep it at or below the version from Debian testing,
|
|
|
to make the distributions' job easier.
|
|
|
|
|
|
rhg
|
|
|
===
|
|
|
|
|
|
There exists an experimental pure-Rust version of Mercurial called `rhg` with a
|
|
|
fallback mechanism for unsupported invocations. It allows for much faster
|
|
|
execution of certain commands while adding no discernable overhead for the rest.
|
|
|
|
|
|
The only way of trying it out is by building it from source. Please refer to
|
|
|
`rust/README.rst` in the Mercurial repository.
|
|
|
|
|
|
See `hg help config.rhg` for configuration options.
|
|
|
|
|
|
Contributing
|
|
|
============
|
|
|
|
|
|
If you would like to help the Rust endeavor, please refer to `rust/README.rst`
|
|
|
in the Mercurial repository.
|
|
|
|
