comparison README.rst @ 6916:a0167e618cfd mercurial-5.4

test-compat: merge mercurial-5.5 into mercurial-5.4

6811:6ea8c0a16d83

* provides an ``hg evolve`` command to deal with such troubles,

* improves performance of obsolescence marker exchange and discovery during
  push and pull.

.. _`changeset evolution`: https://www.mercurial-scm.org/wiki/ChangesetEvolution

Documentation
-------------

We recommend reading the documentation first. An online version is available

You can install the latest released version using pip::

    $ pip install --user hg-evolve

Then enable it in 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 <target revision>`
    $ 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::

    [extensions]
    evolve = ~/evolve/hgext3rd/evolve

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 evolve is installed for the same version of Python that you use for
  running Mercurial (``hg debuginstall | grep Python``).

Extension Purpose
=================

The goal of this extension is to provide an appropriate place for code and

================

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

Python 2 Support
================

Python 2 is supported by evolve. However, Mercurial 6.2 release dropped support

    $ hg email --to [e-mail] --flag evolve-ext --rev '<your patches>'

For guidelines on the patch description, see the `official Mercurial guideline`_.

.. _`official Mercurial guideline`: https://mercurial-scm.org/wiki/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
$HGSRC::

6916:a0167e618cfd

* provides an ``hg evolve`` command to deal with such troubles,

* improves performance of obsolescence marker exchange and discovery during
  push and pull.

.. _`changeset evolution`: https://wiki.mercurial-scm.org/ChangesetEvolution

Documentation
-------------

We recommend reading the documentation first. An online version is available

You can install the latest released version using pip::

    $ pip install --user hg-evolve

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&section=all
.. _`Ubuntu`: https://packages.ubuntu.com/search?keywords=mercurial-evolve&searchon=names&exact=1&suite=all&section=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 <target revision>`
    $ 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 =

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/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``),

* try specifying the full path to the ``hgext3rd/evolve/`` directory.

Extension Purpose
=================

The goal of this extension is to provide an appropriate place for code and

================

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://wiki.mercurial-scm.org/Python3

Python 2 Support
================

Python 2 is supported by evolve. However, Mercurial 6.2 release dropped support

    $ hg email --to [e-mail] --flag evolve-ext --rev '<your patches>'

For guidelines on the patch description, see the `official Mercurial guideline`_.

.. _`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
$HGSRC::