7 |
7 |
8 |
8 |
9 Here are various materials on planned improvement to Mercurial regarding |
9 Here are various materials on planned improvement to Mercurial regarding |
10 rewriting history. |
10 rewriting history. |
11 |
11 |
12 First read about what challenge arise while rewriting history and how we plan to |
12 First, read about what challenges arise while rewriting history and how we plan to |
13 solve them once and for all. |
13 solve them once and for all. |
14 |
14 |
15 .. toctree:: |
15 .. toctree:: |
16 :maxdepth: 2 |
16 :maxdepth: 2 |
17 |
17 |
18 instability |
18 instability |
19 |
19 |
20 The effort is split in two parts: |
20 The effort is split in two parts: |
21 |
21 |
22 * The **obsolescence marker** concept aims to provide an alternative to ``strip`` |
22 * The **obsolescence marker** concept aims to provide an alternative to ``strip`` |
23 to get rid of changesets. This concept have been partially implemented since |
23 to get rid of changesets. This concept has been partially implemented since |
24 Mercurial 2.3. |
24 Mercurial 2.3. |
25 |
25 |
26 * The **evolve** mercurial extension rewrites history using obsolete |
26 * The **evolve** Mercurial extension rewrites history using obsolete |
27 *marker* under the hood. |
27 *marker* under the hood. |
28 |
28 |
29 The first and most important step is by far the **obsolescence marker**. However |
29 The first and most important step is by far the **obsolescence marker**. However |
30 most users will never be directly exposed to the concept. For this reason |
30 most users will never be directly exposed to the concept. For this reason |
31 this manual starts with changeset evolution. |
31 this manual starts with changeset evolution. |
32 |
32 |
33 Evolve: A robust alternative to MQ |
33 Evolve: A robust alternative to MQ |
34 ==================================== |
34 ==================================== |
35 |
35 |
36 Evolve is an experimental history rewriting extension that uses obsolete |
36 Evolve is an experimental history rewriting extension that uses obsolete |
37 markers. It is inspired from MQ and pbranch but have multiple advantages over |
37 markers. It is inspired by MQ and pbranch but has multiple advantages over |
38 them: |
38 them: |
39 |
39 |
40 * Focus on your current work. |
40 * Focus on your current work. |
41 |
41 |
42 You can focus your work on a single changeset and take care of adapting |
42 You can focus your work on a single changeset and take care of adapting |
43 descendent changeset later. |
43 descendent changesets later. |
44 |
44 |
45 * Handle **non-linear history with branches and merges** |
45 * Handle **non-linear history with branches and merges** |
46 |
46 |
47 * Rely internally on **robust merge** mechanism of mercurial. |
47 * Rely internally on Mercurial's **robust merge** mechanism. |
48 |
48 |
49 Simple conflict are handled by real merge tools using appropriate ancestor. |
49 Simple conflicts are handled by real merge tools using the appropriate ancestor. |
50 Conflict are much rarer and much more user friendly. |
50 Conflicts are much rarer and much more user friendly. |
51 |
51 |
52 * Mutable history **fully available all the time**. |
52 * Mutable history **fully available all the time**. |
53 |
53 |
54 always use 'hg update' and forget about (un)applying patches to access the |
54 Always use 'hg update' and forget about (un)applying patches to access the |
55 mutable part of your history. |
55 mutable part of your history. |
56 |
56 |
57 |
57 |
58 * Use only **plain changeset** and forget about patches. Evole will create and |
58 * Use only **plain changesets** and forget about patches. Evolve will create and |
59 exchange real changesets. Mutable history can be used in all usual operations: |
59 exchange real changesets. Mutable history can be used in all usual operations: |
60 pull, push, log, diff, etc. |
60 pull, push, log, diff, etc. |
61 |
61 |
62 * Allow **sharing and collaboration** mutable history without fear of duplicate |
62 * Allow **sharing and collaboration** mutable history without fear of duplicates |
63 (thanks to obsolete marker). |
63 (thanks to obsolete marker). |
64 |
64 |
65 * Cover all mq usage but guard. |
65 * Cover all MQ usage but guard. |
66 |
66 |
67 .. warning:: The evolve extension and obsolete markers are at an experimental |
67 .. warning:: The evolve extension and obsolete markers are at an experimental |
68 stage. While using obsolete you willl likely be exposed to complex |
68 stage. While using obsolete you willl likely be exposed to complex |
69 implications of the **obsolete marker** concept. I do not recommend |
69 implications of the **obsolete marker** concept. I do not recommend |
70 non-power users to test this at this stage. |
70 non-power users to test this at this stage. |
71 |
71 |
72 While numbered 1.0.0, the command line API of this version should |
72 While numbered 1.0.0, the command line API of this version should |
73 **not** be regarded as *stable*, command behavior, name and |
73 **not** be regarded as *stable*: command behavior, name and |
74 options may change in future release or once integrated in |
74 options may change in future releases or once integrated into |
75 mercurial. It is still an immature extension, a lot of |
75 Mercurial. It is still an immature extension; a lot of |
76 features are still missing but there is no high risk of |
76 features are still missing but there is low risk of |
77 repository corruption. |
77 repository corruption. |
78 |
78 |
79 Production ready version should hide such details to normal user. |
79 Production-ready version should hide such details from normal users. |
80 |
80 |
81 The evolve extension requires mercurial 2.4 (older version supports 2.3 and 2.2) |
81 The evolve extension requires Mercurial 2.4 (older versions support 2.3 and 2.2) |
82 |
82 |
83 To enable the evolve extension use:: |
83 To enable the evolve extension use:: |
84 |
84 |
85 $ hg clone https://bitbucket.org/marmoute/mutable-history -u stable |
85 $ hg clone https://bitbucket.org/marmoute/mutable-history -u stable |
86 $ echo '[extensions]\nevolve=$PWD/mutable-history/hgext/evolve.py' >> ~/.hgrc |
86 $ echo '[extensions]\nevolve=$PWD/mutable-history/hgext/evolve.py' >> ~/.hgrc |
106 qsync |
106 qsync |
107 |
107 |
108 Smart changeset deletion: Obsolete Marker |
108 Smart changeset deletion: Obsolete Marker |
109 ========================================== |
109 ========================================== |
110 |
110 |
111 Obsolete marker is a powerful concept that allow mercurial to safely handle |
111 The obsolete marker is a powerful concept that allows Mercurial to safely handle |
112 history rewriting operations. It is a new type of relation between Mercurial |
112 history rewriting operations. It is a new type of relation between Mercurial |
113 changesets that track the result of history rewriting operations. |
113 changesets that tracks the result of history rewriting operations. |
114 |
114 |
115 This concept is simple to define and provides a very solid base to: |
115 This concept is simple to define and provides a very solid base for: |
116 |
116 |
117 - Very fast history rewriting operations, |
117 - very fast history rewriting operations |
118 |
118 |
119 - auditable and reversible history rewriting process, |
119 - auditable and reversible history rewriting process |
120 |
120 |
121 - clean final history, |
121 - clean final history |
122 |
122 |
123 - share and collaborate on mutable parts of the history, |
123 - share and collaborate on mutable parts of the history |
124 |
124 |
125 - gracefully handle history rewriting conflicts, |
125 - gracefully handle history rewriting conflicts |
126 |
126 |
127 - allow various history rewriting UI to collaborate with a underlying common API. |
127 - allow various history rewriting UI to collaborate with a underlying common API |
128 |
128 |
129 --- |
129 --- |
130 |
130 |
131 For more information see documents below |
131 For more information, see the documents below |
132 |
132 |
133 .. toctree:: |
133 .. toctree:: |
134 :maxdepth: 1 |
134 :maxdepth: 1 |
135 |
135 |
136 obs-concept |
136 obs-concept |
137 obs-terms |
137 obs-terms |
138 obs-implementation |
138 obs-implementation |
139 |
139 |
140 |
140 |
141 Known limitation and bug |
141 Known limitations and bugs |
142 ================================= |
142 ================================= |
143 |
143 |
144 Here is a list of know issue that will be fixed later: |
144 Here is a list of known issues that will be fixed later: |
145 |
145 |
146 |
146 |
147 * you need to provide to `graft --continue -O` if you started you |
147 * You need to provide to `graft --continue -O` if you started you |
148 graft using `-O`. |
148 graft using `-O`. |
149 |
149 |
150 you to manually specify target all the time. |
150 you to manually specify target all the time. |
151 |
151 |
152 * trying to exchange obsolete marker with a static http repo will crash. |
152 * Trying to exchange obsolete marker with a static http repo will crash. |
153 |
153 |
154 * Extinct changesets are hidden using the *hidden* feature of mercurial only |
154 * Extinct changesets are hidden using the *hidden* feature of mercurial only |
155 supported by a few commands. |
155 supported by a few commands. |
156 |
156 |
157 Only ``hg log``, ``hgview`` and `hg glog` support it. ``hg head`` or other visual viewer don't. |
157 Only ``hg log``, ``hgview`` and `hg glog` support it. Neither ``hg heads`` nor other visual viewers do. |
158 |
158 |
159 * hg heads show extinct changeset |
159 * hg heads shows extinct changesets. |