Mercurial > evolve

annotate docs/index.rst @ 980:64a2e940e1b2

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
docs: add concepts guide (the set theory behind obsolescence)
author Greg Ward <greg@gerg.ca>
date Fri, 06 Jun 2014 17:20:30 -0400
parents c7b2ccd99dab
children c94aaf6df69c
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
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