1 .. Copyright 2011 Pierre-Yves David <pierre-yves.david@ens-lyon.org> |
1 .. Copyright © 2014 Greg Ward <greg@gerg.ca> |
2 .. Logilab SA <contact@logilab.fr> |
|
3 |
2 |
4 ======================================== |
3 ================================== |
5 Changeset Evolution Experimentation |
4 Changeset Evolution with Mercurial |
6 ======================================== |
5 ================================== |
7 |
6 |
|
7 `evolve`_ is an experimental Mercurial extension for safe mutable history. |
8 |
8 |
9 This is the online documentation of the `evolve extension`_. An experimental |
9 .. _`evolve`: http://mercurial.selenic.com/wiki/EvolveExtension |
10 extension that drive the implementation of the `changeset evolution concept`_ for |
|
11 Mercurial. |
|
12 |
10 |
13 .. _`evolve extension`: http://mercurial.selenic.com/wiki/EvolveExtension |
11 With core Mercurial, changesets are permanent and immutable. You can |
14 .. _`changeset evolution concept`: http://mercurial.selenic.com/wiki/ChangesetEvolution |
12 commit new changesets to modify your source code, but you cannot |
|
13 modify or remove old changesets—they are carved in stone for all |
|
14 eternity. |
15 |
15 |
16 Here are various materials on planned improvement to Mercurial regarding |
16 For years, Mercurial has included various extensions that allow |
17 rewriting history. |
17 history modification: ``rebase``, ``mq``, ``histedit``, and so forth. |
|
18 These are useful and popular extensions, and in fact history |
|
19 modification is one of the big reasons DVCSes (distributed version |
|
20 control systems) like Mercurial took off. |
18 |
21 |
19 First, read about what challenges arise while rewriting history and how we plan to |
22 But there's a catch: until now, Mercurial's various mechanisms for |
20 solve them once and for all. |
23 modifying history have been *unsafe*, in that changesets were |
|
24 destroyed (“stripped”) rather than simply made invisible. |
21 |
25 |
22 .. toctree:: |
26 ``evolve`` makes things better in a couple of ways: |
23 :maxdepth: 2 |
|
24 |
27 |
25 instability |
28 * It changes the behaviour of most existing history modification |
|
29 extensions (``rebase``, ``histedit``, etc.) so they use a safer |
|
30 mechanism (*changeset obsolescence*, covered below) rather than |
|
31 the older, less safe *strip* operation. |
26 |
32 |
27 The effort is split in two parts: |
33 * It provides a new way of modifying history that is roughly |
|
34 equivalent to ``mq`` (but much nicer and safer). |
28 |
35 |
29 * The **obsolescence marker** concept aims to provide an alternative to ``strip`` |
36 It helps to understand that ``evolve`` builds on infrastructure |
30 to get rid of changesets. This concept has been partially implemented since |
37 already in core Mercurial: |
31 Mercurial 2.3. |
|
32 |
38 |
33 * The **evolve** Mercurial extension rewrites history using obsolete |
39 * *Phases* (starting in Mercurial 2.1) allow you to distinguish |
34 *marker* under the hood. |
40 mutable and immutable changesets. We'll cover phases early in the |
|
41 user guide, since understanding phases is essential to |
|
42 understanding ``evolve``. |
35 |
43 |
36 The first and most important step is by far the **obsolescence marker**. However |
44 * *Changeset obsolescence* (starting in Mercurial 2.3) is how |
37 most users will never be directly exposed to the concept. For this reason |
45 Mercurial knows how history has been modified, specifically when |
38 this manual starts with changeset evolution. |
46 one changeset replaces another. In the obsolescence model, a |
|
47 changeset is neither removed nor modified, but is instead marked |
|
48 *obsolete* and typically replaced by a *successor*. Obsolete |
|
49 changesets usually become *hidden* as well. Obsolescence is an |
|
50 invisible feature until you start using ``evolve``, so we'll cover |
|
51 it in the user guide too. |
39 |
52 |
40 Evolve: A robust alternative to MQ |
53 Some of the things you can do with ``evolve`` are: |
41 ==================================== |
|
42 |
54 |
43 Evolve is an experimental history rewriting extension that uses obsolete |
55 * Fix a mistake immediately: “Oops! I just committed a changeset |
44 markers. It is inspired by MQ and pbranch but has multiple advantages over |
56 with a syntax error—I'll fix that and amend the changeset so no |
45 them: |
57 one sees my mistake.” (While this is possible using existing |
|
58 features of core Mercurial, ``evolve`` makes it safer.) |
46 |
59 |
47 * Focus on your current work. |
60 * Fix a mistake a little bit later: “Oops! I broke the tests three |
|
61 commits back, but only noticed it now—I'll just update back to the |
|
62 bad changeset, fix my mistake, amend the changeset, and evolve |
|
63 history to update the affected changesets.” |
48 |
64 |
49 You can focus your work on a single changeset and take care of adapting |
65 * Remove unwanted changes: “I hacked in some debug output two |
50 descendent changesets later. |
66 commits back; everything is working now, so I'll just prune that |
|
67 unwanted changeset and evolve history before pushing.” |
51 |
68 |
52 * Handle **non-linear history with branches and merges** |
69 * Share mutable history with yourself: say you do most of your |
|
70 programming work locally, but need to test on a big remote server |
|
71 somewhere before you know everything is good. You can use |
|
72 ``evolve`` to share mutable history between two computers, pushing |
|
73 finely polished changesets to a public repository only after |
|
74 testing on the test server. |
53 |
75 |
54 * Rely internally on Mercurial's **robust merge** mechanism. |
76 * Share mutable history for code review: you don't want to publish |
|
77 unreviewed changesets, but you can't block every commit waiting |
|
78 for code review. The solution is to share mutable history with |
|
79 your reviewer, amending each changeset until it passes review. |
55 |
80 |
56 Simple conflicts are handled by real merge tools using the appropriate ancestor. |
81 ``evolve`` is experimental! |
57 Conflicts are much rarer and much more user friendly. |
82 --------------------------- |
58 |
83 |
59 * Mutable history **fully available all the time**. |
84 TODO |
60 |
85 |
61 Always use 'hg update' and forget about (un)applying patches to access the |
86 * unstable UI |
62 mutable part of your history. |
87 * some corner cases not covered yet |
63 |
88 |
|
89 Installation and setup |
|
90 ---------------------- |
64 |
91 |
65 * Use only **plain changesets** and forget about patches. Evolve will create and |
92 TODO |
66 exchange real changesets. Mutable history can be used in all usual operations: |
|
67 pull, push, log, diff, etc. |
|
68 |
93 |
69 * Allow **sharing and collaboration** mutable history without fear of duplicates |
94 Next steps: |
70 (thanks to obsolete marker). |
95 * For a practical guide to using ``evolve`` in a single repository, |
|
96 see the `user guide`_ (coming soon). |
|
97 * For more advanced tricks, see `sharing mutable history`_ (coming soon). |
|
98 * To learn about the concepts underlying ``evolve``, see `concepts`_ |
|
99 (coming soon). |
|
100 * If you're coming from MQ, see the `MQ migration guide`_ (incomplete). |
71 |
101 |
72 * Cover all MQ usage but guard. |
102 .. _`user guide`: user-guide.html |
73 |
103 .. _`concepts`: concepts.html |
74 .. warning:: The evolve extension and obsolete markers are at an experimental |
104 .. _`sharing mutable history`: sharing.html |
75 stage. While using obsolete you willl likely be exposed to complex |
105 .. _`MQ migration guide`: from-mq.html |
76 implications of the **obsolete marker** concept. I do not recommend |
|
77 non-power users to test this at this stage. |
|
78 |
|
79 While numbered 1.0.0, the command line API of this version should |
|
80 **not** be regarded as *stable*: command behavior, name and |
|
81 options may change in future releases or once integrated into |
|
82 Mercurial. It is still an immature extension; a lot of |
|
83 features are still missing but there is low risk of |
|
84 repository corruption. |
|
85 |
|
86 Production-ready version should hide such details from normal users. |
|
87 |
|
88 The evolve extension requires Mercurial 2.5 (older versions supports down to 2.2) |
|
89 |
|
90 To enable the evolve extension use:: |
|
91 |
|
92 $ hg clone https://bitbucket.org/marmoute/mutable-history -u stable |
|
93 $ echo '[extensions]\nevolve=$PWD/mutable-history/hgext/evolve.py' >> ~/.hgrc |
|
94 |
|
95 You will probably want to use hgview_ to visualize obsolescence. Version 1.7.1 |
|
96 or later is required. |
|
97 |
|
98 .. _hgview: http://www.logilab.org/project/hgview/ |
|
99 |
|
100 |
|
101 --- |
|
102 |
|
103 For more information see the documents below: |
|
104 |
|
105 .. toctree:: |
|
106 :maxdepth: 1 |
|
107 |
|
108 tutorials/tutorial |
|
109 evolve-good-practice |
|
110 evolve-faq |
|
111 from-mq |
|
112 evolve-collaboration |
|
113 qsync |
|
114 |
|
115 Smart changeset deletion: Obsolete Marker |
|
116 ========================================== |
|
117 |
|
118 The obsolete marker is a powerful concept that allows Mercurial to safely handle |
|
119 history rewriting operations. It is a new type of relation between Mercurial |
|
120 changesets that tracks the result of history rewriting operations. |
|
121 |
|
122 This concept is simple to define and provides a very solid base for: |
|
123 |
|
124 - very fast history rewriting operations |
|
125 |
|
126 - auditable and reversible history rewriting process |
|
127 |
|
128 - clean final history |
|
129 |
|
130 - share and collaborate on mutable parts of the history |
|
131 |
|
132 - gracefully handle history rewriting conflicts |
|
133 |
|
134 - allow various history rewriting UI to collaborate with a underlying common API |
|
135 |
|
136 --- |
|
137 |
|
138 For more information, see the documents below |
|
139 |
|
140 .. toctree:: |
|
141 :maxdepth: 1 |
|
142 |
|
143 obs-concept |
|
144 obs-terms |
|
145 obs-implementation |
|
146 |
|
147 |
|
148 Known limitations and bugs |
|
149 ================================= |
|
150 |
|
151 Here is a list of known issues that will be fixed later: |
|
152 |
|
153 |
|
154 * You need to provide to `graft --continue -O` if you started you |
|
155 graft using `-O`. |
|
156 |
|
157 you to manually specify target all the time. |
|
158 |
|
159 * Trying to exchange obsolete marker with a static http repo will crash. |
|
160 |
|
161 * Extinct changesets are hidden using the *hidden* feature of mercurial only |
|
162 supported by a few commands. |
|
163 |
|
164 Only ``hg log``, ``hgview`` and `hg glog` support it. Neither ``hg heads`` nor other visual viewers do. |
|
165 |
|
166 * hg heads shows extinct changesets. |
|