Mercurial > evolve

comparison docs/index.rst @ 2887:c1cf3c8947f1

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
index: edit pass by native english speaker
author Ryan McElroy <rmcelroy@fb.com>
date Wed, 30 Aug 2017 17:32:32 +0200
parents 5a836fa589a4
children 31aa9d097d29
comparison
equal deleted inserted replaced
2886:00518926094f 2887:c1cf3c8947f1
11 those changes to other repositories. 11 those changes to other repositories.
12 12
13 * It can automatically detect and handle the complex issues that can arise from 13 * It can automatically detect and handle the complex issues that can arise from
14 exchanging draft changesets. 14 exchanging draft changesets.
15 15
16 * It makes it even possible for multiple developers to rewrite the same part of 16 * It even makes it possible for multiple developers to safely rewrite the same
17 the history in a distributed way. 17 parts of history in a distributed way.
18 18
19 * It fully respects the Phases concept so unsure users will only rewrite parts 19 * It fully respects the Phases concept so users will only be able to rewrite
20 of the history that are safe to be changed. Phases have been part of Mercurial 20 parts of the history that are safe to change. Phases have been part of
21 since early 2012. 21 Mercurial since early 2012.
22 22
23 .. _`evolve`: https://www.mercurial-scm.org/wiki/EvolveExtension 23 .. _`evolve`: https://www.mercurial-scm.org/wiki/EvolveExtension
24 .. _`Mercurial`: https://www.mercurial-scm.org/ 24 .. _`Mercurial`: https://www.mercurial-scm.org/
25 25
26 Installation and setup 26 Installation and setup
38 Then add in your `hgrc` config:: 38 Then add in your `hgrc` config::
39 39
40 [extensions] 40 [extensions]
41 evolve= 41 evolve=
42 42
43 You can easily edit the `hgrc` of repository using `hg config --local` or your 43 You can easily edit the `hgrc` of a repository using `hg config --local`.
44 user configuration `hg config --edit`. 44 Alternatively, you can edit your user configuration with `hg config --edit`.
45 45
46 Table of Content 46 Table of Contents
47 ---------------- 47 -----------------
48 48
49 .. toctree:: 49 .. toctree::
50 :maxdepth: 2 50 :maxdepth: 2
51 51
52 index 52 index
55 concepts 55 concepts
56 from-mq 56 from-mq
57 57
58 .. _`changeset evolution`: 58 .. _`changeset evolution`:
59 59
60 What is Changeset Evolution ? 60 What is Changeset Evolution?
61 ----------------------------- 61 ----------------------------
62 62
63 With core Mercurial, changesets are permanent and immutable. You can 63 With core Mercurial, changesets are permanent and immutable. You can
64 commit new changesets to modify your source code, but you cannot 64 commit new changesets to modify your source code, but you cannot
65 modify or remove old changesets. 65 modify or remove old changesets.
66 66
67 For years, Mercurial has included various commands that allow 67 For years, Mercurial has included various commands that allow
68 history modification: ``rebase``, ``histedit``, ``commit --amend`` and so forth. 68 history modification: ``rebase``, ``histedit``, ``commit --amend`` and so forth.
69 But there's a catch: until now, Mercurial's various mechanisms for 69 However, there's a catch: until now, Mercurial's various mechanisms for
70 modifying history have been *unsafe*, in that changesets were 70 modifying history have been *unsafe*, in that changesets were
71 destroyed (“stripped”) rather than simply made hidden. 71 destroyed (“stripped”) rather than simply hidden and still easy to recover.
72 72
73 ``evolve`` makes things better by changing the behaviour of most existing 73 ``evolve`` makes things better by changing the behaviour of most existing
74 history modification commands so they use a safer mechanism (*changeset 74 history modification commands so they use a safer mechanism (*changeset
75 obsolescence*, covered below) rather than the older, less safe *strip* 75 obsolescence*, covered below) rather than the older, less safe *strip*
76 operation. 76 operation.
83 * *Changeset obsolescence* (starting in Mercurial 2.3) is how 83 * *Changeset obsolescence* (starting in Mercurial 2.3) is how
84 Mercurial knows how history has been modified, specifically when 84 Mercurial knows how history has been modified, specifically when
85 one changeset replaces another. In the obsolescence model, a 85 one changeset replaces another. In the obsolescence model, a
86 changeset is neither removed nor modified, but is instead marked 86 changeset is neither removed nor modified, but is instead marked
87 *obsolete* and typically replaced by a *successor*. Obsolete 87 *obsolete* and typically replaced by a *successor*. Obsolete
88 changesets usually become *hidden* as well. Obsolescence is an 88 changesets usually become *hidden* as well. Obsolescence is a
89 disabled feature in Mercurial until you start using ``evolve``. 89 disabled feature in Mercurial until you start using ``evolve``.
90 90
91 Some of the things you can do with ``evolve`` are: 91 Some of the things you can do with ``evolve`` are:
92 92
93 * Fix a mistake immediately: “Oops! I just committed a changeset 93 * Fix a mistake immediately: “Oops! I just committed a changeset
115 unreviewed changesets, but you can't block every commit waiting 115 unreviewed changesets, but you can't block every commit waiting
116 for code review. The solution is to share mutable history with 116 for code review. The solution is to share mutable history with
117 your reviewer, amending each changeset until it passes review. 117 your reviewer, amending each changeset until it passes review.
118 118
119 * Explore and audit the rewrite history of a changeset. Since Mercurial is 119 * Explore and audit the rewrite history of a changeset. Since Mercurial is
120 tracking the edition you make to a changeset, you can look at the history of 120 tracking the edits you make to a changeset, you can look at the history of
121 these editions. This is similar to Mercurial tracking the history of a file 121 these edits. This is similar to Mercurial tracking the history of file
122 edition, but at the changeset level. 122 edits, but at the changeset level.
123 123
124 Why the `evolve` extension 124 Why the `evolve` extension?
125 -------------------------- 125 ---------------------------
126 126
127 Mercurial core already has some support for `changeset evolution`_ so why have a 127 Mercurial core already has some support for `changeset evolution`_ so why have a
128 dedicated extension? 128 dedicated extension?
129 129
130 The long-term plan for ``evolve`` is to add it to core Mercurial. However, 130 The long-term plan for ``evolve`` is to add it to core Mercurial. However,
131 having the extension helps us experimenting with various user experience 131 having the extension helps us experiment with various user experience
132 approaches and technical prototype. Having a dedicated extensions help current 132 approaches and technical prototypes. Having a dedicated extension helps current
133 user to deploy the later changes quickly and provides the developers with 133 users deploy the latest changes quickly and provides developers with low latency
134 low latency feedbacks. 134 feedback.
135 135
136 Whenever we are happy with a direction experimented in the extension, the 136 Whenever we are happy with a experimental direction in the extension, the
137 relevant code go upstream. 137 relevant code can go upstream into Core Mercurial.
138 138
139 Development status 139 Development status
140 ------------------ 140 ------------------
141 141
142 While well on the way, the full implementation of the `changeset evolution`_ 142 While well underway, the full implementation of the `changeset evolution`_
143 concept is still in progress. Core Mercurial already supports many of the 143 concept is still a work in progress. Core Mercurial already supports many of the
144 associated features, but for now they are still disabled by default. The current 144 associated features, but for now they are still disabled by default. The current
145 implementation has been usable for multiple years already, and some parts of it 145 implementation has been usable for multiple years already, and some parts of it
146 are used in production in multiple projects and companies (including the 146 are used in production by multiple projects and companies (including the
147 Mercurial project itself, Facebook, Google, etc…). 147 Mercurial project itself, Facebook, Google, etc…).
148 148
149 However, there are still some areas were the current implementation has gaps. 149 However, there are still some areas were the current implementation has gaps.
150 This means some use cases or performance issues are not handled as well as they 150 This means some use cases or performance issues are not handled as well as they
151 currently are without evolution. Mercurial has been around for a long time and 151 currently are without evolution. Mercurial has been around for a long time and
152 is strongly committed to backward compatibility, and turning evolution on by 152 is strongly committed to backward compatibility. Therefore turning evolution on
153 default nowadays could regress the experience of some of our current users. The 153 by default today could regress the experience of some of our current users. The
154 feature will be enabled by default at the point where users who do not use or 154 features will only be enabled by default at the point where users who do not use
155 care about the new features added by evolution won't be impacted by it. 155 or care about the new features added by evolution won't be negatively impacted
156 by the new default.
156 157
157 .. # .. _`this query`: https://bz.mercurial-scm.org/buglist.cgi?component=evolution&bug_status=UNCONFIRMED&bug_status=CONFIRMED&bug_status=NEED_EXAMPLE 158 .. # .. _`this query`: https://bz.mercurial-scm.org/buglist.cgi?component=evolution&bug_status=UNCONFIRMED&bug_status=CONFIRMED&bug_status=NEED_EXAMPLE
158 159
159 Ressources 160 Resources
160 ---------- 161 ---------
161 162
162 * For a practical guide to using ``evolve`` in a single repository, 163 * For a practical guide to using ``evolve`` in a single repository,
163 see the `user guide`_. 164 see the `user guide`_.
164 * For more advanced tricks, see `sharing mutable history`_. 165 * For more advanced tricks, see `sharing mutable history`_.
165 * To learn about the concepts underlying ``evolve``, see `concepts`_ 166 * To learn about the concepts underlying ``evolve``, see `concepts`_