docs/index.rst
author Durham Goode <durham@fb.com>
Thu, 19 Mar 2015 10:52:28 -0700
changeset 1218 dd5e62979100
parent 980 64a2e940e1b2
child 1266 c94aaf6df69c
permissions -rw-r--r--
wrapcommand: allow adding additional arguments to commands This allows eh.wrapcommand to specify additional parameters to be added to the commands being wrapped. This will be useful when wrapping strip in the future.
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
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
     7
`evolve`_ is an experimental Mercurial extension for safe mutable history.
709
60582b861a00 minor help changes
Pierre-Yves David <pierre-yves.david@ens-lyon.org>
parents: 667
diff changeset
     8
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
     9
.. _`evolve`: http://mercurial.selenic.com/wiki/EvolveExtension
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    10
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    11
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
    12
commit new changesets to modify your source code, but you cannot
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    13
modify or remove old changesets—they are carved in stone for all
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    14
eternity.
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    15
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    16
For years, Mercurial has included various extensions that allow
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    17
history modification: ``rebase``, ``mq``, ``histedit``, and so forth.
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    18
These are useful and popular extensions, and in fact history
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    19
modification is one of the big reasons DVCSes (distributed version
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    20
control systems) like Mercurial took off.
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    21
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    22
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
    23
modifying history have been *unsafe*, in that changesets were
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    24
destroyed (“stripped”) rather than simply made invisible.
163
92b073d13f2d more doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 161
diff changeset
    25
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    26
``evolve`` makes things better in a couple of ways:
227
abe52cf492ee doc: several update and review.
Pierre-Yves.David@ens-lyon.org
parents: 194
diff changeset
    27
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    28
  * It changes the behaviour of most existing history modification
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    29
    extensions (``rebase``, ``histedit``, etc.) so they use a safer
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    30
    mechanism (*changeset obsolescence*, covered below) rather than
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    31
    the older, less safe *strip* operation.
164
c81d286c4a5b improved intro about evolve
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    32
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    33
  * It provides a new way of modifying history that is roughly
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    34
    equivalent to ``mq`` (but much nicer and safer).
164
c81d286c4a5b improved intro about evolve
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    35
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    36
It helps to understand that ``evolve`` builds on infrastructure
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    37
already in core Mercurial:
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    38
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    39
  * *Phases* (starting in Mercurial 2.1) allow you to distinguish
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    40
    mutable and immutable changesets. We'll cover phases early in the
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    41
    user guide, since understanding phases is essential to
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    42
    understanding ``evolve``.
227
abe52cf492ee doc: several update and review.
Pierre-Yves.David@ens-lyon.org
parents: 194
diff changeset
    43
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    44
  * *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
    45
    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
    46
    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
    47
    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
    48
    *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
    49
    changesets usually become *hidden* as well. Obsolescence is an
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    50
    invisible feature until you start using ``evolve``, so we'll cover
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    51
    it in the user guide too.
163
92b073d13f2d more doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 161
diff changeset
    52
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    53
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
    54
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    55
  * 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
    56
    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
    57
    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
    58
    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
    59
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    60
  * 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
    61
    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
    62
    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
    63
    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
    64
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    65
  * 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
    66
    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
    67
    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
    68
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    69
  * 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
    70
    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
    71
    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
    72
    ``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
    73
    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
    74
    testing on the test server.
166
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 165
diff changeset
    75
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    76
  * 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
    77
    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
    78
    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
    79
    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
    80
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    81
``evolve`` is experimental!
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    82
---------------------------
166
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 165
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
TODO
166
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 165
diff changeset
    85
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    86
  * unstable UI
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    87
  * some corner cases not covered yet
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    88
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    89
Installation and setup
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    90
----------------------
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    91
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    92
TODO
227
abe52cf492ee doc: several update and review.
Pierre-Yves.David@ens-lyon.org
parents: 194
diff changeset
    93
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    94
Next steps:
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    95
  * 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
    96
    see the `user guide`_.
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents: 978
diff changeset
    97
  * 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
    98
  * 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
    99
    (incomplete).
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
   100
  * 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
   101
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
   102
.. _`user guide`: user-guide.html
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
   103
.. _`concepts`: concepts.html
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
   104
.. _`sharing mutable history`: sharing.html
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
   105
.. _`MQ migration guide`: from-mq.html