# HG changeset patch # User Anton Shestakov # Date 1721649433 -14400 # Node ID 9c70bdc92cdb35c67d45dda93f0bf48a1a3ea359 # Parent 4f02e7f8d56c8b00f911980f2a3ac0768a5e3e53 docs: update installation instructions due to PEP 668 diff -r 4f02e7f8d56c -r 9c70bdc92cdb README.rst --- a/README.rst Fri Aug 23 17:00:28 2024 +0400 +++ b/README.rst Mon Jul 22 15:57:13 2024 +0400 @@ -26,7 +26,7 @@ * improves performance of obsolescence marker exchange and discovery during push and pull. -.. _`changeset evolution`: https://www.mercurial-scm.org/wiki/ChangesetEvolution +.. _`changeset evolution`: https://wiki.mercurial-scm.org/ChangesetEvolution Documentation ------------- @@ -48,44 +48,101 @@ $ pip install --user hg-evolve -Then enable it in your hgrc:: +Note: some distributions have adopted PEP 668 and made using ``pip install +--user`` more difficult than it should be. One of the cleanest ways around this +issue is to install both Mercurial and this extension in a separate virtual +environment. If you don't want to manage the virtual environment manually, you +can use Pipx. + +Using Pipx +---------- + +Its documentation explains that "pipx is made specifically for application +installation", and the idea is that for every application it can create and +maintain a separate virtual environment and make all executables available on a +single path (e.g. ~/.local/bin/ on Linux, check ``pipx ensurepath``). + +To create a virtual environment for hg and install evolve:: + + $ pipx install mercurial + $ pipx inject mercurial hg-evolve + # or pipx runpip mercurial install hg-evolve + +Note: it's recommended to use ``inject`` command to install evolve, but +sometimes ``runpip`` could be used. On some setups ``inject`` might require +specifying the full path to the extension in the configuration file, while +``runpip`` might not. + +Using Your Package Manager +-------------------------- + +Sometimes your distribution's package manager might have the newest (or recent +enough) version of the extension. For example, both `Debian`_ and `Ubuntu`_ +currently have a package called ``mercurial-evolve``. Similarly, other +distributions might have it packaged, possibly under a slightly different name. +Try searching your package manager's database or see `this Repology page`_. + +.. _`Debian`: https://packages.debian.org/search?keywords=mercurial-evolve&searchon=names&exact=1&suite=all§ion=all +.. _`Ubuntu`: https://packages.ubuntu.com/search?keywords=mercurial-evolve&searchon=names&exact=1&suite=all§ion=all +.. _`this Repology page`: https://repology.org/project/mercurial-evolve/related + +From Source +----------- + +To obtain a local version from source:: + + $ hg clone https://repo.mercurial-scm.org/evolve + +There's no need to compile anything or run ``make``. + +This method keeps the extension in its own repo, and you can use it by +specifying the full path to the ``hgext3rd/evolve/``. + +Alternatively, you can install it:: + + $ cd evolve + # optionally `hg update ` + $ pip install --user . + +This should avoid the need to specify the full path to the extension. + +Enabling the Extension +---------------------- + +After installing the extension, you need to enable it before you can use it. + +To do that, edit your hgrc:: $ hg config --edit # add these two lines: [extensions] evolve = -From Source ------------ - -To install a local version from source:: - - $ hg clone https://www.mercurial-scm.org/repo/evolve/ - $ cd evolve - # optionally `hg update ` - $ pip install --user . - -Then enable it in your hgrc:: - - $ hg config --edit # add these two lines: - [extensions] - evolve = - -It's also possible to use evolve without installing it, in which case you will -need to provide the full path to ``hgext3rd/evolve/``, for example:: +If you didn't install the extension or Mercurial can't find it on one of the +default paths, you need to specify the full path to ``hgext3rd/evolve/``:: [extensions] evolve = ~/evolve/hgext3rd/evolve +Similarly, if you want to enable topic extension, do this:: + + $ hg config --edit + [extensions] + topic = + # or + topic = ~/evolve/hgext3rd/topic + Pitfalls -------- If you get ``"failed to import extension evolve: No module named 'evolve'"`` error, there are a couple of things to check: -* make sure you gave pip the correct package name (it's hg-evolve), +* make sure you gave pip/pipx the correct package name (it's ``hg-evolve``), * make sure evolve is installed for the same version of Python that you use for - running Mercurial (``hg debuginstall | grep Python``). + running Mercurial (``hg debuginstall | grep Python``), + +* try specifying the full path to the ``hgext3rd/evolve/`` directory. Extension Purpose ================= @@ -110,7 +167,7 @@ Mercurial announced official `support for Python 3`_ starting with its 5.2 release. Since 9.3.0, evolve has official support for Python 3.6+. -.. _`support for Python 3`: https://www.mercurial-scm.org/wiki/Python3 +.. _`support for Python 3`: https://wiki.mercurial-scm.org/Python3 Python 2 Support ================ @@ -146,7 +203,7 @@ For guidelines on the patch description, see the `official Mercurial guideline`_. -.. _`official Mercurial guideline`: https://mercurial-scm.org/wiki/ContributingChanges#Patch_descriptions +.. _`official Mercurial guideline`: https://wiki.mercurial-scm.org/ContributingChanges#Patch_descriptions Please don't forget to update and run the tests when you fix a bug or add a feature. To run the tests, you need a working copy of Mercurial, say in