docs/index.rst
author Pierre-Yves David <pierre-yves.david@octobus.net>
Tue, 29 Aug 2017 17:11:18 +0200
changeset 2875 483152bab9b9
parent 2874 2b84eee4c040
child 2876 c47c988b239b
permissions -rw-r--r--
doc-front-page: mention the mailing list in the documentation It is an important tool to keep people up to date.
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
     1
.. Copyright © 2014 Greg Ward <greg@gerg.ca>
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
     2
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
     3
==================================
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
     4
Changeset Evolution with Mercurial
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
     5
==================================
709
60582b861a00 minor help changes
Pierre-Yves David <pierre-yves.david@ens-lyon.org>
parents: 667
diff changeset
     6
2873
2c4171a53475 doc-front-page: move introduction before the table of content
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2872
diff changeset
     7
`evolve`_ is a Mercurial extension for faster and safer mutable history.
2c4171a53475 doc-front-page: move introduction before the table of content
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2872
diff changeset
     8
2c4171a53475 doc-front-page: move introduction before the table of content
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2872
diff changeset
     9
.. _`evolve`: https://www.mercurial-scm.org/wiki/EvolveExtension
2c4171a53475 doc-front-page: move introduction before the table of content
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2872
diff changeset
    10
2874
2b84eee4c040 doc-front-page: move installation instruction earliero
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2873
diff changeset
    11
Installation and setup
2b84eee4c040 doc-front-page: move installation instruction earliero
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2873
diff changeset
    12
----------------------
2b84eee4c040 doc-front-page: move installation instruction earliero
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2873
diff changeset
    13
2875
483152bab9b9 doc-front-page: mention the mailing list in the documentation
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2874
diff changeset
    14
We recommend you subscribe to the `evolve-testers`_ mailing list to stay up
483152bab9b9 doc-front-page: mention the mailing list in the documentation
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2874
diff changeset
    15
to date with the latest news and announcement.
483152bab9b9 doc-front-page: mention the mailing list in the documentation
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2874
diff changeset
    16
483152bab9b9 doc-front-page: mention the mailing list in the documentation
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2874
diff changeset
    17
.. _`evolve-testers`: https://www.mercurial-scm.org/mailman/listinfo/evolve-testers
483152bab9b9 doc-front-page: mention the mailing list in the documentation
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2874
diff changeset
    18
2874
2b84eee4c040 doc-front-page: move installation instruction earliero
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2873
diff changeset
    19
Using pip::
2b84eee4c040 doc-front-page: move installation instruction earliero
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2873
diff changeset
    20
2b84eee4c040 doc-front-page: move installation instruction earliero
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2873
diff changeset
    21
    pip install --user hg-evolve
2b84eee4c040 doc-front-page: move installation instruction earliero
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2873
diff changeset
    22
2b84eee4c040 doc-front-page: move installation instruction earliero
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2873
diff changeset
    23
Then add in your `hgrc` config::
2b84eee4c040 doc-front-page: move installation instruction earliero
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2873
diff changeset
    24
2b84eee4c040 doc-front-page: move installation instruction earliero
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2873
diff changeset
    25
   [extensions]
2b84eee4c040 doc-front-page: move installation instruction earliero
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2873
diff changeset
    26
   evolve=
2b84eee4c040 doc-front-page: move installation instruction earliero
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2873
diff changeset
    27
2b84eee4c040 doc-front-page: move installation instruction earliero
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2873
diff changeset
    28
You can easily edit the `hgrc` of repository using `hg config --local` or your
2b84eee4c040 doc-front-page: move installation instruction earliero
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2873
diff changeset
    29
user configuration `hg config --edit`.
2b84eee4c040 doc-front-page: move installation instruction earliero
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2873
diff changeset
    30
1284
e33990a4c27a docs: add a table of contents
Greg Ward <greg@gerg.ca>
parents: 1266
diff changeset
    31
.. toctree::
e33990a4c27a docs: add a table of contents
Greg Ward <greg@gerg.ca>
parents: 1266
diff changeset
    32
   :maxdepth: 2
e33990a4c27a docs: add a table of contents
Greg Ward <greg@gerg.ca>
parents: 1266
diff changeset
    33
e33990a4c27a docs: add a table of contents
Greg Ward <greg@gerg.ca>
parents: 1266
diff changeset
    34
   user-guide
e33990a4c27a docs: add a table of contents
Greg Ward <greg@gerg.ca>
parents: 1266
diff changeset
    35
   sharing
e33990a4c27a docs: add a table of contents
Greg Ward <greg@gerg.ca>
parents: 1266
diff changeset
    36
   concepts
e33990a4c27a docs: add a table of contents
Greg Ward <greg@gerg.ca>
parents: 1266
diff changeset
    37
   from-mq
e33990a4c27a docs: add a table of contents
Greg Ward <greg@gerg.ca>
parents: 1266
diff changeset
    38
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    39
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    40
With core Mercurial, changesets are permanent and immutable. You can
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    41
commit new changesets to modify your source code, but you cannot
2871
c6289ec369cb doc: be less dramatic about changeset immutability
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2870
diff changeset
    42
modify or remove old changesets.
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    43
2872
78debdfb3e4d doc: simplify the reference to in-core features
Philippe Pepiot <phil@philpep.org>
parents: 2871
diff changeset
    44
For years, Mercurial has included various commands that allow
78debdfb3e4d doc: simplify the reference to in-core features
Philippe Pepiot <phil@philpep.org>
parents: 2871
diff changeset
    45
history modification: ``rebase``, ``histedit``, ``commit --amend`` and so forth.
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    46
But there's a catch: until now, Mercurial's various mechanisms for
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    47
modifying history have been *unsafe*, in that changesets were
2861
54a95c333102 doc: use "hidden" instead of "invisible"
Philippe Pepiot <phil@philpep.org>
parents: 2557
diff changeset
    48
destroyed (“stripped”) rather than simply made hidden.
163
92b073d13f2d more doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 161
diff changeset
    49
2872
78debdfb3e4d doc: simplify the reference to in-core features
Philippe Pepiot <phil@philpep.org>
parents: 2871
diff changeset
    50
``evolve`` makes things better by changing the behaviour of most existing
78debdfb3e4d doc: simplify the reference to in-core features
Philippe Pepiot <phil@philpep.org>
parents: 2871
diff changeset
    51
history modification commands so they use a safer mechanism (*changeset
78debdfb3e4d doc: simplify the reference to in-core features
Philippe Pepiot <phil@philpep.org>
parents: 2871
diff changeset
    52
obsolescence*, covered below) rather than the older, less safe *strip*
78debdfb3e4d doc: simplify the reference to in-core features
Philippe Pepiot <phil@philpep.org>
parents: 2871
diff changeset
    53
operation.
227
abe52cf492ee doc: several update and review.
Pierre-Yves.David@ens-lyon.org
parents: 194
diff changeset
    54
2872
78debdfb3e4d doc: simplify the reference to in-core features
Philippe Pepiot <phil@philpep.org>
parents: 2871
diff changeset
    55
``evolve`` is built on infrastructure in core Mercurial:
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    56
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    57
  * *Phases* (starting in Mercurial 2.1) allow you to distinguish
2872
78debdfb3e4d doc: simplify the reference to in-core features
Philippe Pepiot <phil@philpep.org>
parents: 2871
diff changeset
    58
    mutable and immutable changesets.
227
abe52cf492ee doc: several update and review.
Pierre-Yves.David@ens-lyon.org
parents: 194
diff changeset
    59
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    60
  * *Changeset obsolescence* (starting in Mercurial 2.3) is how
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    61
    Mercurial knows how history has been modified, specifically when
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    62
    one changeset replaces another. In the obsolescence model, a
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    63
    changeset is neither removed nor modified, but is instead marked
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    64
    *obsolete* and typically replaced by a *successor*. Obsolete
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    65
    changesets usually become *hidden* as well. Obsolescence is an
2872
78debdfb3e4d doc: simplify the reference to in-core features
Philippe Pepiot <phil@philpep.org>
parents: 2871
diff changeset
    66
    invisible feature in Mercurial until you start using ``evolve``.
163
92b073d13f2d more doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 161
diff changeset
    67
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    68
Some of the things you can do with ``evolve`` are:
163
92b073d13f2d more doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 161
diff changeset
    69
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    70
  * Fix a mistake immediately: “Oops! I just committed a changeset
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    71
    with a syntax error—I'll fix that and amend the changeset so no
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    72
    one sees my mistake.” (While this is possible using existing
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    73
    features of core Mercurial, ``evolve`` makes it safer.)
166
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 165
diff changeset
    74
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    75
  * Fix a mistake a little bit later: “Oops! I broke the tests three
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    76
    commits back, but only noticed it now—I'll just update back to the
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    77
    bad changeset, fix my mistake, amend the changeset, and evolve
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    78
    history to update the affected changesets.”
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    79
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    80
  * Remove unwanted changes: “I hacked in some debug output two
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    81
    commits back; everything is working now, so I'll just prune that
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    82
    unwanted changeset and evolve history before pushing.”
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    83
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    84
  * Share mutable history with yourself: say you do most of your
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    85
    programming work locally, but need to test on a big remote server
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    86
    somewhere before you know everything is good. You can use
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    87
    ``evolve`` to share mutable history between two computers, pushing
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    88
    finely polished changesets to a public repository only after
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    89
    testing on the test server.
166
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 165
diff changeset
    90
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    91
  * Share mutable history for code review: you don't want to publish
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    92
    unreviewed changesets, but you can't block every commit waiting
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    93
    for code review. The solution is to share mutable history with
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    94
    your reviewer, amending each changeset until it passes review.
166
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 165
diff changeset
    95
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    96
``evolve`` is experimental!
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    97
---------------------------
166
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 165
diff changeset
    98
1266
c94aaf6df69c docs: flesh out unfinished bits in the intro page
Greg Ward <greg@gerg.ca>
parents: 980
diff changeset
    99
The long-term plan for ``evolve`` is to add it to core Mercurial.
c94aaf6df69c docs: flesh out unfinished bits in the intro page
Greg Ward <greg@gerg.ca>
parents: 980
diff changeset
   100
However, it is not yet stable enough for that. In particular:
c94aaf6df69c docs: flesh out unfinished bits in the intro page
Greg Ward <greg@gerg.ca>
parents: 980
diff changeset
   101
c94aaf6df69c docs: flesh out unfinished bits in the intro page
Greg Ward <greg@gerg.ca>
parents: 980
diff changeset
   102
  * The UI is unstable: ``evolve``'s command names and command options
c94aaf6df69c docs: flesh out unfinished bits in the intro page
Greg Ward <greg@gerg.ca>
parents: 980
diff changeset
   103
    are not completely nailed down yet. They are subject to occasional
c94aaf6df69c docs: flesh out unfinished bits in the intro page
Greg Ward <greg@gerg.ca>
parents: 980
diff changeset
   104
    backwards-incompatible changes. If you write scripts that use
c94aaf6df69c docs: flesh out unfinished bits in the intro page
Greg Ward <greg@gerg.ca>
parents: 980
diff changeset
   105
    evolve commands, a future release could break your scripts.
166
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 165
diff changeset
   106
1266
c94aaf6df69c docs: flesh out unfinished bits in the intro page
Greg Ward <greg@gerg.ca>
parents: 980
diff changeset
   107
  * There are still some corner cases that aren't handled yet. If you
c94aaf6df69c docs: flesh out unfinished bits in the intro page
Greg Ward <greg@gerg.ca>
parents: 980
diff changeset
   108
    think you have found such a case, please check if it's already
1724
bd994fd256e1 docs: point wiki and bz links to mercurial-scm.org
Anton Shestakov <av6@dwimlabs.net>
parents: 1617
diff changeset
   109
    described in the Mercurial bug tracker (https://bz.mercurial-scm.org/).
1266
c94aaf6df69c docs: flesh out unfinished bits in the intro page
Greg Ward <greg@gerg.ca>
parents: 980
diff changeset
   110
    Bugs in ``evolve`` are files under component "evolution": use
c94aaf6df69c docs: flesh out unfinished bits in the intro page
Greg Ward <greg@gerg.ca>
parents: 980
diff changeset
   111
    `this query`_ to view open bugs in ``evolve``.
c94aaf6df69c docs: flesh out unfinished bits in the intro page
Greg Ward <greg@gerg.ca>
parents: 980
diff changeset
   112
1724
bd994fd256e1 docs: point wiki and bz links to mercurial-scm.org
Anton Shestakov <av6@dwimlabs.net>
parents: 1617
diff changeset
   113
.. _`this query`: https://bz.mercurial-scm.org/buglist.cgi?component=evolution&bug_status=UNCONFIRMED&bug_status=CONFIRMED&bug_status=NEED_EXAMPLE
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   114
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
   115
Next steps:
1266
c94aaf6df69c docs: flesh out unfinished bits in the intro page
Greg Ward <greg@gerg.ca>
parents: 980
diff changeset
   116
-----------
c94aaf6df69c docs: flesh out unfinished bits in the intro page
Greg Ward <greg@gerg.ca>
parents: 980
diff changeset
   117
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
   118
  * For a practical guide to using ``evolve`` in a single repository,
978
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents: 977
diff changeset
   119
    see the `user guide`_.
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents: 978
diff changeset
   120
  * For more advanced tricks, see `sharing mutable history`_.
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
   121
  * To learn about the concepts underlying ``evolve``, see `concepts`_
980
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents: 979
diff changeset
   122
    (incomplete).
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
   123
  * If you're coming from MQ, see the `MQ migration guide`_ (incomplete).
364
616305c63510 doc: cleanup in caveat and 2.1 compat
Pierre-Yves.David@ens-lyon.org
parents: 363
diff changeset
   124
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
   125
.. _`user guide`: user-guide.html
1284
e33990a4c27a docs: add a table of contents
Greg Ward <greg@gerg.ca>
parents: 1266
diff changeset
   126
.. _`sharing mutable history`: sharing.html
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
   127
.. _`concepts`: concepts.html
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
   128
.. _`MQ migration guide`: from-mq.html