2 |
2 |
3 ================================== |
3 ================================== |
4 Changeset Evolution with Mercurial |
4 Changeset Evolution with Mercurial |
5 ================================== |
5 ================================== |
6 |
6 |
|
7 `evolve`_ is a Mercurial extension for faster and safer mutable history. It |
|
8 implements the `changeset evolution`_ concept for `Mercurial`_. |
|
9 |
|
10 * It offers a safe and simple way to refine changesets locally and propagate |
|
11 those changes to other repositories. |
|
12 |
|
13 * It can automatically detect and handle the complex issues that can arise from |
|
14 exchanging draft changesets. |
|
15 |
|
16 * It even makes it possible for multiple developers to safely rewrite the same |
|
17 parts of history in a distributed way. |
|
18 |
|
19 * It fully respects the Phases concept so users will only be able to rewrite |
|
20 parts of the history that are safe to change. Phases have been part of |
|
21 Mercurial since early 2012. |
|
22 |
|
23 .. _`evolve`: https://www.mercurial-scm.org/wiki/EvolveExtension |
|
24 .. _`Mercurial`: https://www.mercurial-scm.org/ |
|
25 |
|
26 Installation and setup |
|
27 ---------------------- |
|
28 |
|
29 We recommend you subscribe to the `evolve-testers`_ mailing list to stay up |
|
30 to date with the latest news and announcement. |
|
31 |
|
32 .. _`evolve-testers`: https://www.mercurial-scm.org/mailman/listinfo/evolve-testers |
|
33 |
|
34 Using pip:: |
|
35 |
|
36 pip install --user hg-evolve |
|
37 |
|
38 Then add in your `hgrc` config:: |
|
39 |
|
40 [extensions] |
|
41 evolve= |
|
42 |
|
43 You can easily edit the `hgrc` of a repository using `hg config --local`. |
|
44 Alternatively, you can edit your user configuration with `hg config --edit`. |
|
45 |
|
46 Table of Contents |
|
47 ----------------- |
|
48 |
7 .. toctree:: |
49 .. toctree:: |
8 :maxdepth: 2 |
50 :maxdepth: 2 |
9 |
51 |
|
52 index |
10 user-guide |
53 user-guide |
11 sharing |
54 sharing |
12 concepts |
55 concepts |
13 from-mq |
56 from-mq |
|
57 commands |
|
58 known-doc-issues |
14 |
59 |
15 `evolve`_ is an experimental Mercurial extension for safe mutable history. |
60 .. _`changeset evolution`: |
16 |
61 |
17 .. _`evolve`: https://www.mercurial-scm.org/wiki/EvolveExtension |
62 What is Changeset Evolution? |
|
63 ---------------------------- |
18 |
64 |
19 With core Mercurial, changesets are permanent and immutable. You can |
65 With core Mercurial, changesets are permanent and immutable. You can |
20 commit new changesets to modify your source code, but you cannot |
66 commit new changesets to modify your source code, but you cannot |
21 modify or remove old changesets—they are carved in stone for all |
67 modify or remove old changesets. |
22 eternity. |
|
23 |
68 |
24 For years, Mercurial has included various extensions that allow |
69 For years, Mercurial has included various commands that allow |
25 history modification: ``rebase``, ``mq``, ``histedit``, and so forth. |
70 history modification: ``rebase``, ``histedit``, ``commit --amend`` and so forth. |
26 These are useful and popular extensions, and in fact history |
71 However, there's a catch: until now, Mercurial's various mechanisms for |
27 modification is one of the big reasons DVCSes (distributed version |
72 modifying history have been *unsafe*, in that changesets were |
28 control systems) like Mercurial took off. |
73 destroyed (“stripped”) rather than simply hidden and still easy to recover. |
29 |
74 |
30 But there's a catch: until now, Mercurial's various mechanisms for |
75 ``evolve`` makes things better by changing the behaviour of most existing |
31 modifying history have been *unsafe*, in that changesets were |
76 history modification commands so they use a safer mechanism (*changeset |
32 destroyed (“stripped”) rather than simply made invisible. |
77 obsolescence*, covered below) rather than the older, less safe *strip* |
|
78 operation. |
33 |
79 |
34 ``evolve`` makes things better in a couple of ways: |
80 ``evolve`` is built on infrastructure in core Mercurial: |
35 |
|
36 * It changes the behaviour of most existing history modification |
|
37 extensions (``rebase``, ``histedit``, etc.) so they use a safer |
|
38 mechanism (*changeset obsolescence*, covered below) rather than |
|
39 the older, less safe *strip* operation. |
|
40 |
|
41 * It provides a new way of modifying history that is roughly |
|
42 equivalent to ``mq`` (but much nicer and safer). |
|
43 |
|
44 It helps to understand that ``evolve`` builds on infrastructure |
|
45 already in core Mercurial: |
|
46 |
81 |
47 * *Phases* (starting in Mercurial 2.1) allow you to distinguish |
82 * *Phases* (starting in Mercurial 2.1) allow you to distinguish |
48 mutable and immutable changesets. We'll cover phases early in the |
83 mutable and immutable changesets. |
49 user guide, since understanding phases is essential to |
|
50 understanding ``evolve``. |
|
51 |
84 |
52 * *Changeset obsolescence* (starting in Mercurial 2.3) is how |
85 * *Changeset obsolescence* (starting in Mercurial 2.3) is how |
53 Mercurial knows how history has been modified, specifically when |
86 Mercurial knows how history has been modified, specifically when |
54 one changeset replaces another. In the obsolescence model, a |
87 one changeset replaces another. In the obsolescence model, a |
55 changeset is neither removed nor modified, but is instead marked |
88 changeset is neither removed nor modified, but is instead marked |
56 *obsolete* and typically replaced by a *successor*. Obsolete |
89 *obsolete* and typically replaced by a *successor*. Obsolete |
57 changesets usually become *hidden* as well. Obsolescence is an |
90 changesets usually become *hidden* as well. Obsolescence is a |
58 invisible feature until you start using ``evolve``, so we'll cover |
91 disabled feature in Mercurial until you start using ``evolve``. |
59 it in the user guide too. |
|
60 |
92 |
61 Some of the things you can do with ``evolve`` are: |
93 Some of the things you can do with ``evolve`` are: |
62 |
94 |
63 * Fix a mistake immediately: “Oops! I just committed a changeset |
95 * Fix a mistake immediately: “Oops! I just committed a changeset |
64 with a syntax error—I'll fix that and amend the changeset so no |
96 with a syntax error—I'll fix that and amend the changeset so no |
65 one sees my mistake.” (While this is possible using existing |
97 one sees my mistake.” (While this is possible using default |
66 features of core Mercurial, ``evolve`` makes it safer.) |
98 features of core Mercurial, changeset evolution makes it safer.) |
67 |
99 |
68 * Fix a mistake a little bit later: “Oops! I broke the tests three |
100 * Fix a mistake a little bit later: “Oops! I broke the tests three |
69 commits back, but only noticed it now—I'll just update back to the |
101 commits back, but only noticed it now—I'll just update back to the |
70 bad changeset, fix my mistake, amend the changeset, and evolve |
102 bad changeset, fix my mistake, amend the changeset, and evolve |
71 history to update the affected changesets.” |
103 history to update the affected changesets.” |
84 * Share mutable history for code review: you don't want to publish |
116 * Share mutable history for code review: you don't want to publish |
85 unreviewed changesets, but you can't block every commit waiting |
117 unreviewed changesets, but you can't block every commit waiting |
86 for code review. The solution is to share mutable history with |
118 for code review. The solution is to share mutable history with |
87 your reviewer, amending each changeset until it passes review. |
119 your reviewer, amending each changeset until it passes review. |
88 |
120 |
89 ``evolve`` is experimental! |
121 * Explore and audit the rewrite history of a changeset. Since Mercurial is |
|
122 tracking the edits you make to a changeset, you can look at the history of |
|
123 these edits. This is similar to Mercurial tracking the history of file |
|
124 edits, but at the changeset level. |
|
125 |
|
126 Why the `evolve` extension? |
90 --------------------------- |
127 --------------------------- |
91 |
128 |
92 The long-term plan for ``evolve`` is to add it to core Mercurial. |
129 Mercurial core already has some support for `changeset evolution`_ so why have a |
93 However, it is not yet stable enough for that. In particular: |
130 dedicated extension? |
94 |
131 |
95 * The UI is unstable: ``evolve``'s command names and command options |
132 The long-term plan for ``evolve`` is to add it to core Mercurial. However, |
96 are not completely nailed down yet. They are subject to occasional |
133 having the extension helps us experiment with various user experience |
97 backwards-incompatible changes. If you write scripts that use |
134 approaches and technical prototypes. Having a dedicated extension helps current |
98 evolve commands, a future release could break your scripts. |
135 users deploy the latest changes quickly and provides developers with low latency |
|
136 feedback. |
99 |
137 |
100 * There are still some corner cases that aren't handled yet. If you |
138 Whenever we are happy with a experimental direction in the extension, the |
101 think you have found such a case, please check if it's already |
139 relevant code can go upstream into Core Mercurial. |
102 described in the Mercurial bug tracker (https://bz.mercurial-scm.org/). |
|
103 Bugs in ``evolve`` are files under component "evolution": use |
|
104 `this query`_ to view open bugs in ``evolve``. |
|
105 |
140 |
106 .. _`this query`: https://bz.mercurial-scm.org/buglist.cgi?component=evolution&bug_status=UNCONFIRMED&bug_status=CONFIRMED&bug_status=NEED_EXAMPLE |
141 Development status |
|
142 ------------------ |
107 |
143 |
108 Installation and setup |
144 While well underway, the full implementation of the `changeset evolution`_ |
109 ---------------------- |
145 concept is still a work in progress. Core Mercurial already supports many of the |
|
146 associated features, but for now they are still disabled by default. The current |
|
147 implementation has been usable for multiple years already, and some parts of it |
|
148 are used in production by multiple projects and companies (including the |
|
149 Mercurial project itself, Facebook, Google, etc…). |
110 |
150 |
111 To use ``evolve``, you must: |
151 However, there are still some areas were the current implementation has gaps. |
|
152 This means some use cases or performance issues are not handled as well as they |
|
153 currently are without evolution. Mercurial has been around for a long time and |
|
154 is strongly committed to backward compatibility. Therefore turning evolution on |
|
155 by default today could regress the experience of some of our current users. The |
|
156 features will only be enabled by default at the point where users who do not use |
|
157 or care about the new features added by evolution won't be negatively impacted |
|
158 by the new default. |
112 |
159 |
113 #. Clone the ``evolve`` repository:: |
160 .. # .. _`this query`: https://bz.mercurial-scm.org/buglist.cgi?component=evolution&bug_status=UNCONFIRMED&bug_status=CONFIRMED&bug_status=NEED_EXAMPLE |
114 |
161 |
115 cd ~/src |
162 Resources |
116 hg clone https://www.mercurial-scm.org/repo/evolve |
163 --------- |
117 |
|
118 #. Configure the extension, either locally :: |
|
119 |
|
120 hg config --local |
|
121 |
|
122 or for all your repositories :: |
|
123 |
|
124 hg config --edit |
|
125 |
|
126 Then add :: |
|
127 |
|
128 evolve=~/src/evolve-main/hgext3rd/evolve/ |
|
129 |
|
130 in the ``[extensions]`` section (adding the section if necessary). Use |
|
131 the directory that you actually cloned to, of course. |
|
132 |
|
133 |
|
134 Next steps: |
|
135 ----------- |
|
136 |
164 |
137 * For a practical guide to using ``evolve`` in a single repository, |
165 * For a practical guide to using ``evolve`` in a single repository, |
138 see the `user guide`_. |
166 see the `user guide`_. |
139 * For more advanced tricks, see `sharing mutable history`_. |
167 * For more advanced tricks, see `sharing mutable history`_. |
140 * To learn about the concepts underlying ``evolve``, see `concepts`_ |
168 * To learn about the concepts underlying ``evolve``, see `concepts`_ |