Mercurial > evolve

annotate docs/index.rst @ 2875:483152bab9b9

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc-front-page: mention the mailing list in the documentation It is an important tool to keep people up to date.
author Pierre-Yves David <pierre-yves.david@octobus.net>
date Tue, 29 Aug 2017 17:11:18 +0200
parents 2b84eee4c040
children c47c988b239b
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
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