annotate docs/index.rst @ 978:8328337d23b2

docs: add new user guide This has also been reviewed to death on evolve-testers. There are still a couple of short sections to write (clearly marked "TODO"), and one example to add. But (if I may be so bold) this is a gigantic improvement over the current docs, so it really should get merged. Incidentally, the figures are all SVG files created with Inkscape. They're not perfect, but they're pretty nice. Anyone who knows a better way to create technical diagrams is welcome to contribute. One wart: there's a test script that accompanies the document and largely duplicates it, but I haven't unified them. I've been concentrating on writing the best possible content, not on fiddling with tools. I suspect that unifying them will be non-trivial, but definitely worth doing.
author Greg Ward <greg@gerg.ca>
date Thu, 05 Jun 2014 22:11:04 -0400
parents cc0f0d94bf30
children c7b2ccd99dab
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`_.
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
97 * For more advanced tricks, see `sharing mutable history`_ (coming soon).
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`_
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
99 (coming soon).
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