annotate docs/user-guide.rst @ 3926:35172bd95e57 stable

compat: ignore extra status feature for hg <= 4.3 The feature does not exist in 4.3 and below.
author Pierre-Yves David <pierre-yves.david@octobus.net>
date Thu, 02 Aug 2018 03:08:52 +0200
parents 83d2c9637e89
children 8406d9b06130
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
978
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
1 .. Copyright © 2014 Greg Ward <greg@gerg.ca>
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
2
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
3 ------------------
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
4 Evolve: User Guide
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
5 ------------------
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
6
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
7 .. contents::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
8
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
9 Life without ``evolve``
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
10 -----------------------
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
11
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
12 Before we dive into learning about ``evolve``, let's look into some
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
13 features of core Mercurial that interact with ``evolve``. ``commit``
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
14 affects ``evolve``, and ``evolve`` modifies how ``commit --amend``
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
15 works.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
16
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
17 Example 1: Commit a new changeset
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
18 =================================
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
19
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
20 To create a new changeset, simply run ``hg commit`` as usual.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
21 ``evolve`` does not change the behaviour of ``commit`` at all.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
22
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
23 However, it's important to understand that new changesets are in the
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
24 *draft* phase by default: they are mutable. This means that they can
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
25 be modified by Mercurial's existing history-editing commands
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
26 (``rebase``, ``histedit``, etc.), and also by the ``evolve``
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
27 extension. Specifically, ``evolve`` adds a number of commands that can
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
28 be used to modify history: ``amend``, ``uncommit``, ``prune``,
2931
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
29 ``fold``, and ``evolve``. ::
978
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
30
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
31 $ hg commit -m 'implement feature X'
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
32 $ hg phase -r .
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
33 1: draft
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
34
2931
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
35 Generally speaking, changesets remain in *draft* phase until they are
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
36 pushed to another repository, at which point they enter the *public*
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
37 phase. (Strictly speaking, changesets only become public when they are
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
38 pushed to a *publishing* repository. But all repositories are publishing
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
39 by default; you have to explicitly configure repositories to be
978
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
40 *non-publishing*. Non-publishing repositories are an advanced topic
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
41 which we'll see when we get to `sharing mutable history`_.)
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
42
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
43 .. _`sharing mutable history`: sharing.html
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
44
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
45 Example 2: Amend a changeset (traditional)
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
46 ==========================================
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
47
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
48 Imagine you've just committed a new changeset, and then you discover a
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
49 mistake. Maybe you forgot to run the tests and a failure slipped in.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
50 You want to modify history so that you push one perfect changeset,
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
51 rather than one flawed changeset followed by an "oops" commit. (Or
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
52 perhaps you made a typo in the commit message—this is really feature
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
53 *Y*, not feature X. You can't fix that with a followup commit.)
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
54
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
55 This is actually trivial with plain vanilla Mercurial since 2.2: fix
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
56 your mistake and run ::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
57
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
58 $ hg commit --amend -m 'implement feature Y'
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
59
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
60 to create a new, amended changeset. The drawback of doing this with
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
61 vanilla Mercurial is that your original, flawed, changeset is removed
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
62 from the repository. This is *unsafe* history editing. It's probably
2931
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
63 not too serious if all you did was fix a syntax error, but for deeper
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
64 changes there can be more serious consequences to unsafe history editing.
978
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
65
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
66 .. figure:: figures/figure-ug01.svg
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
67
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
68 Figure 1: unsafe history modification with core Mercurial (not
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
69 using ``evolve``): the original revision 1 is destroyed.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
70
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
71 (Incidentally, Mercurial's traditional history modification mechanism
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
72 isn't *really* unsafe: any changeset(s) removed from the repository
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
73 are kept in a backup directory, so you can manually restore them later
2931
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
74 if you change your mind. However, this mechanism is very awkward and
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
75 inconvenient compared to the features provided by ``evolve`` and
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
76 changeset obsolescence.)
978
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
77
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
78 Life with ``evolve`` (basic usage)
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
79 ----------------------------------
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
80
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
81 Once you enable the ``evolve`` extension, a number of features are
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
82 available to you. First, we're going to explore several examples of
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
83 painless, trouble-free history modification.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
84
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
85 Example 3: Amend a changeset (with ``evolve``)
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
86 ==============================================
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
87
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
88 Outwardly, amending a changeset with ``evolve`` can look exactly the
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
89 same as it does with core Mercurial (example 2)::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
90
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
91 $ hg commit --amend -m 'implement feature Y'
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
92
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
93 Alternately, you can use the new ``amend`` command added by
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
94 ``evolve``::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
95
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
96 $ hg amend -m 'implement feature Y'
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
97
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
98 (``hg amend`` is nearly synonymous with ``hg commit --amend``. The
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
99 difference is that ``hg amend`` reuses the existing commit message by
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
100 default, whereas ``hg commit --amend`` runs your editor if you don't
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
101 pass ``-m`` or ``-l``.)
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
102
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
103 Under the hood, though, things are quite different. Mercurial has
2931
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
104 simply marked the old changeset as *obsolete*, replacing it with a new
978
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
105 one. We'll explore what this means in detail later, after working
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
106 through a few more examples.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
107
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
108 Example 4: Prune an unwanted changeset
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
109 ======================================
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
110
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
111 Sometimes you make a change, and then decide it was such a bad idea
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
112 that you don't want anyone to know about it. Or maybe it was a
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
113 debugging hack that you needed to keep around for a while, but do not
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
114 intend to ever push publicly. ::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
115
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
116 $ echo 'debug hack' >> file1.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
117 $ hg commit -m 'debug hack'
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
118
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
119 In either case, ``hg prune`` is the answer. ``prune`` simply marks
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
120 changesets obsolete without creating any new changesets to replace
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
121 them::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
122
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
123 $ hg prune .
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
124 1 changesets pruned
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
125 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
126 working directory now at 934359450037
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
127
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
128 Outwardly, it appears that your “debug hack” commit never happened;
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
129 we're right back where we started::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
130
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
131 $ hg parents --template '{rev}:{node|short} {desc|firstline}\n'
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
132 3:934359450037 implement feature Y
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
133
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
134 In reality, though, the “debug hack” is still there, obsolete and hidden.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
135
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
136 Example 5: Uncommit changes to certain files
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
137 ============================================
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
138
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
139 Occasionally you commit more than you intended: perhaps you made
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
140 unrelated changes to different files, and thus intend to commit
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
141 different files separately. ::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
142
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
143 $ echo 'relevant' >> file1.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
144 $ echo 'irrelevant' >> file2.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
145
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
146 If you forget to specify filenames on the ``commit`` command line,
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
147 Mercurial commits all those changes together::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
148
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
149 $ hg commit -m 'fix bug 234' # oops: too many files
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
150
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
151 Luckily, this mistake is easy to fix with ``uncommit``::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
152
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
153 $ hg uncommit file2.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
154 $ hg status
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
155 M file2.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
156
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
157 Let's verify that the replacement changeset looks right (i.e.,
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
158 modifies only ``file1.c``)::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
159
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
160 $ hg parents --template '{rev}:{node|short} {desc|firstline}\n{files}\n'
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
161 6:c8defeecf7a4 fix bug 234
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
162 file1.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
163
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
164 As before, the original flawed changeset is still there, but obsolete
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
165 and hidden. It won't be exchanged with other repositories by ``push``,
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
166 ``pull``, or ``clone``.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
167
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
168 Example 6: Fold multiple changesets together into one
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
169 =====================================================
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
170
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
171 If you're making extensive changes to fragile source code, you might
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
172 commit more frequently than normal so that you can fallback on a
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
173 known good state if one step goes badly. ::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
174
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
175 $ echo step1 >> file1.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
176 $ hg commit -m 'step 1' # revision 7
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
177 $ echo step2 >> file1.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
178 $ hg commit -m 'step 2' # revision 8
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
179 $ echo step3 >> file2.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
180 $ hg commit -m 'step 3' # revision 9
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
181
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
182 At the end of such a sequence, you often end up with a series of small
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
183 changesets that are tedious to review individually. It might make more
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
184 sense to combine them into a single changeset using the ``fold``
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
185 command.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
186
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
187 To make sure we pass the right revisions to ``fold``, let's review the
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
188 changesets we just created, from revision 7::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
189
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
190 $ hg log --template '{rev}:{node|short} {desc|firstline}\n' -r 7::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
191 7:05e61aab8294 step 1
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
192 8:be6d5bc8e4cc step 2
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
193 9:35f432d9f7c1 step 3
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
194
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
195 and fold them::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
196
2931
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
197 $ hg fold -m 'fix bug 64' -r 7:: --exact
978
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
198 3 changesets folded
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
199 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
200
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
201 This time, Mercurial marks three changesets obsolete, replacing them
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
202 all with a single *successor*.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
203
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
204 (You might be familiar with this operation under other names, like
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
205 *squash* or *collapse*.)
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
206
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
207 Changeset obsolescence under the hood
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
208 -------------------------------------
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
209
1267
8cc6e90354a9 docs: tweak wording, punctuation for better readability
Greg Ward <greg@gerg.ca>
parents: 978
diff changeset
210 So far, everything has gone just fine: we haven't run into merge
978
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
211 conflicts or other trouble. Before we start exploring advanced usage
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
212 that can run into trouble, let's step back and see what happens when
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
213 Mercurial marks changesets obsolete. That will make it much easier to
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
214 understand the more advanced use cases we'll see later.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
215
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
216 When you have the ``evolve`` extension enabled, all history
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
217 modification uses the same underlying mechanism: the original
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
218 changesets are marked *obsolete* and replaced by zero or more
2931
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
219 *successors*. The obsolete changesets are the *predecessors* of their
978
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
220 successors. This applies equally to built-in commands (``commit
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
221 --amend``), commands added by ``evolve`` (``amend``, ``prune``,
1267
8cc6e90354a9 docs: tweak wording, punctuation for better readability
Greg Ward <greg@gerg.ca>
parents: 978
diff changeset
222 ``uncommit``, ``fold``), and commands provided by other extensions
8cc6e90354a9 docs: tweak wording, punctuation for better readability
Greg Ward <greg@gerg.ca>
parents: 978
diff changeset
223 (``rebase``, ``histedit``).
978
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
224
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
225 Another way of looking at it is that obsolescence is second-order
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
226 version control, i.e. the history of your history. We'll cover this in
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
227 more detail (and mathematical precision) in the `concepts`_ guide.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
228
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
229 .. _`concepts`: concepts.html
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
230
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
231 Under the hood: Amend a changeset
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
232 =================================
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
233
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
234 Consider Example 2, amending a changeset with ``evolve``. We saw above
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
235 that you can do this using the exact same command-line syntax as core
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
236 Mercurial, namely ``hg commit --amend``. But the implementation is
2931
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
237 quite different, as Figure 2 shows.
978
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
238
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
239 .. figure:: figures/figure-ug02.svg
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
240
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
241 Figure 2: safe history modification using ``evolve``: the original
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
242 revision 1 is preserved as an obsolete changeset. (The "temporary
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
243 amend commit", marked with T, is an implementation detail stemming
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
244 from limitations in Mercurial's current merge machinery. Future
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
245 versions of Mercurial will not create them.)
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
246
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
247 In this case, the obsolete changesets are also *hidden*. That is the
2931
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
248 usual end state for obsolete changesets. However, many scenarios result
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
249 in obsolete changesets that are still visible, which indicates your
978
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
250 history modification work is not yet done. We'll see examples of that
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
251 later, when we cover advanced usage.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
252
1268
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
253
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
254 Understanding revision numbers and hidden changesets
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
255 ====================================================
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
256
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
257 As the name implies, hidden changesets are normally not visible. If
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
258 you run ``hg log`` on the repository from Figure 2, Mercurial will
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
259 show revisions 0 and 3, but not 1 and 2. That's something you don't
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
260 see with plain vanilla Mercurial—normally, revision *N* is always
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
261 followed by revision *N* + 1.
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
262
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
263 This is just the visible manifestation of hidden changesets. If
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
264 revision 0 is followed by revision 3, that means there are two hidden
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
265 changesets, 1 and 2, in between.
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
266
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
267 To see those hidden changesets, use the ``--hidden`` option::
978
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
268
1268
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
269 $ hg --hidden log --graph --template '{rev}:{node|short} {desc|firstline}\n'
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
270 @ 3:934359450037 implement feature Y
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
271 |
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
272 | x 2:6c5f78d5d467 temporary amend commit for fe0ecd3bd2a4
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
273 | |
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
274 | x 1:fe0ecd3bd2a4 implement feature Y
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
275 |/
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
276 o 0:08c4b6f4efc8 init
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
277
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
278 Note that changeset IDs are still the permanent, immutable identifier
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
279 for changesets. Revision numbers are, as ever, a handy shorthand that
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
280 work in your local repository, but cannot be used across repositories.
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
281 They also have the useful property of showing when there are hidden
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
282 changesets lurking under the covers, which is why this document uses
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
283 revision numbers.
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
284
978
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
285
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
286 Under the hood: Prune an unwanted changeset
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
287 ===========================================
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
288
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
289 ``prune`` (example 4 above) is the simplest history modification
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
290 command provided by ``evolve``. All it does is mark the specified
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
291 changeset(s) obsolete, with no successor/precursor relationships
2931
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
292 involved. (If the working directory parent was one of the obsoleted
978
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
293 changesets, ``prune`` updates back to a suitable ancestor.)
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
294
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
295 .. figure:: figures/figure-ug03.svg
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
296
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
297 Figure 3: pruning a changeset marks it obsolete with no successors.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
298
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
299 Under the hood: Uncommit changes to certain files
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
300 =================================================
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
301
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
302 In one sense, ``uncommit`` is a simplified version of ``amend``. Like
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
303 ``amend``, it obsoletes one changeset and leaves it with a single
2931
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
304 successor. In another sense, ``uncommit`` is the inverse of ``amend``:
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
305 ``amend`` takes any uncommitted changes in the working dir and “adds”
978
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
306 them to the working directory's parent changeset. (In reality, of
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
307 course, it creates a successor changeset, marking the original
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
308 obsolete.) In contrast, ``uncommit`` takes some changes in the working
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
309 directory's parent and moves them to the working dir, creating a new
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
310 successor changeset in the process. Figure 4 illustrates.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
311
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
312 .. figure:: figures/figure-ug04.svg
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
313
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
314 Figure 4: uncommit moves some of the changes from the working
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
315 directory parent into the working dir, preserving the remaining
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
316 changes as a new successor changeset. (N.B. revision 4 is not shown
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
317 here because it was marked obsolete in the previous example.)
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
318
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
319
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
320 Under the hood: Fold multiple changesets together into one
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
321 ==========================================================
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
322
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
323 The last basic example is folding multiple changesets into one, which
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
324 marks multiple changesets obsolete, replacing them all with a single
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
325 successor.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
326
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
327 .. figure:: figures/figure-ug05.svg
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
328
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
329 Figure 5: fold combines multiple changesets into a single
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
330 successor, marking the original (folded) changesets obsolete.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
331
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
332
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
333 Obsolete is not hidden
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
334 ======================
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
335
1269
250835154f8f docs: explain that obsolete is not hidden
Greg Ward <greg@gerg.ca>
parents: 1268
diff changeset
336 So far, every obsolete changeset we have seen is also hidden. However,
250835154f8f docs: explain that obsolete is not hidden
Greg Ward <greg@gerg.ca>
parents: 1268
diff changeset
337 these are *not* the same thing—that's why they have different names.
250835154f8f docs: explain that obsolete is not hidden
Greg Ward <greg@gerg.ca>
parents: 1268
diff changeset
338 It's entirely possible to have obsolete changesets that are not
250835154f8f docs: explain that obsolete is not hidden
Greg Ward <greg@gerg.ca>
parents: 1268
diff changeset
339 hidden. We'll see examples of that soon, when we create *unstable*
250835154f8f docs: explain that obsolete is not hidden
Greg Ward <greg@gerg.ca>
parents: 1268
diff changeset
340 changesets.
250835154f8f docs: explain that obsolete is not hidden
Greg Ward <greg@gerg.ca>
parents: 1268
diff changeset
341
250835154f8f docs: explain that obsolete is not hidden
Greg Ward <greg@gerg.ca>
parents: 1268
diff changeset
342 Note that all hidden changesets are obsolete: hidden is a subset of
2931
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
343 obsolete. This is explained in more depth in the `concepts`_ section.
978
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
344
2931
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
345 .. _`concepts`: concepts.html
978
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
346
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
347 Life with ``evolve`` (advanced usage)
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
348 -------------------------------------
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
349
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
350 Now that you've got a solid understanding of how ``evolve`` works in
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
351 concert with changeset obsolescence, let's explore some more advanced
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
352 scenarios. All of these scenarios will involve *unstable* changesets,
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
353 which is an unavoidable consequence of obsolescence. What really sets
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
354 ``evolve`` apart from other history modification mechanisms is the
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
355 fact that it recognizes troubles like unstable changesets and provides
2931
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
356 a consistent way for you to get back to a stable repository.
978
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
357
2931
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
358 (Incidentally, there are two other types of troubles that changesets
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
359 can get into with ``evolve``: they may be *divergent* or
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
360 *bumped*. Both of those states are more likely to occur when
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
361 `sharing mutable history`_, so we won't cover them in this user guide.)
978
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
362
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
363 .. _`sharing mutable history`: sharing.html
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
364
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
365
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
366 Example 7: Amend an older changeset
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
367 ===================================
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
368
2931
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
369 Sometimes you don't notice a mistake until after you have committed
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
370 new changesets on top of the changeset with the mistake. ::
978
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
371
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
372 $ hg commit -m 'fix bug 17' # rev 11 (mistake here)
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
373 $ hg commit -m 'cleanup' # rev 12
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
374 $ hg commit -m 'feature 23' # rev 13
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
375
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
376 Traditionally, your only option is to commit an "oops" changeset that
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
377 fixes your mistake. That works, of course, but it makes you look bad:
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
378 you made a mistake, and the record of that mistake is recorded in
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
379 history for all eternity. (If the mistake was in the commit message,
1267
8cc6e90354a9 docs: tweak wording, punctuation for better readability
Greg Ward <greg@gerg.ca>
parents: 978
diff changeset
380 too bad: you cannot fix it.)
978
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
381
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
382 More subtly, there now exist changesets that are *worse* than what
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
383 came before—the code no longer builds, the tests don't pass, or
1267
8cc6e90354a9 docs: tweak wording, punctuation for better readability
Greg Ward <greg@gerg.ca>
parents: 978
diff changeset
384 similar. Anyone reviewing these patches will waste time on the error
8cc6e90354a9 docs: tweak wording, punctuation for better readability
Greg Ward <greg@gerg.ca>
parents: 978
diff changeset
385 in the earlier patch, and then the correction later on.
978
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
386
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
387 You can avoid all this by amending the bad changeset and *evolving*
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
388 subsequent history. Here's how it works, assuming you have just
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
389 committed revision 13 and noticed the mistake in revision 11::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
390
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
391 $ hg update 11
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
392 [...fix mistake...]
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
393 $ hg amend
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
394
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
395 At this point, revision 11 is *obsolete* and revisions 12 and 13—the
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
396 descendants of 11—are in a funny state: they are *unstable*.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
397
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
398 .. figure:: figures/figure-ug06.svg
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
399
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
400 Figure 6: amending a changeset with descendants means the amended
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
401 changeset is obsolete but remains visible; its non-obsolete
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
402 descendants are *unstable*. The temporary amend commit, revision
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
403 14, is hidden because it has no non-obsolete descendants.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
404
2931
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
405 All non-obsolete descendants of an obsolete changeset are considered
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
406 unstable. An interesting consequence of this is that revision 11 is
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
407 still visible, even though it is obsolete. Obsolete changesets with
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
408 non-obsolete descendants are not hidden.
978
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
409
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
410 The fix is to *evolve* history::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
411
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
412 $ hg evolve --all
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
413
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
414 This is a separate step, not automatically part of ``hg amend``,
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
415 because there might be conflicts. If your amended changeset modifies a
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
416 file that one of its descendants also modified, Mercurial has to fire
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
417 up your merge tool to resolve the conflict. More importantly, you have
2931
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
418 to switch from "writing code" to "resolving conflicts". That can be an
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
419 expensive context switch, so Mercurial lets you decide when to do it.
978
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
420
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
421 The end state, after ``evolve`` finishes, is that the original
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
422 revisions (11-13) are obsolete and hidden. Their successor revisions
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
423 (15-17) replace them.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
424
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
425 .. figure:: figures/figure-ug07.svg
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
426
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
427 Figure 7: evolve your repository (``hg evolve --all``) to take care
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
428 of instability. Unstable changesets become obsolete, and are
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
429 replaced by successors just like the amended changeset was.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
430
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
431 Example 8: Prune an older changeset
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
432 ===================================
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
433
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
434 Let's say you've just committed the following changesets::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
435
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
436 $ hg commit -m 'useful work' # rev 18
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
437 $ hg commit -m 'debug hack' # rev 19
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
438 $ hg commit -m 'more work' # rev 20
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
439
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
440 You want to drop revision 19, but keep 18 and 20. No problem::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
441
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
442 $ hg prune 19
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
443 1 changesets pruned
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
444 1 new unstable changesets
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
445
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
446 As above, this leaves your repository in a funny intermediate state:
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
447 revision 20 is the non-obsolete descendant of obsolete revision 19.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
448 That is, revision 20 is unstable.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
449
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
450 .. figure:: figures/figure-ug08.svg
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
451
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
452 Figure 8: ``hg prune`` marks a changeset obsolete without creating
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
453 a successor. Just like with ``hg amend``, non-obsolete descendants
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
454 of the pruned changeset are now unstable.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
455
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
456 As before, the solution to unstable changesets is to evolve your
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
457 repository::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
458
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
459 $ hg evolve --all
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
460
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
461 This rebases revision 20 on top of 18 as the new revision 21, leaving
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
462 19 and 20 obsolete and hidden:
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
463
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
464 .. figure:: figures/figure-ug09.svg
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
465
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
466 Figure 9: once again, ``hg evolve --all`` takes care of instability.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
467
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
468 Example 9: Uncommit files from an older changeset (discard changes)
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
469 =======================================================================
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
470
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
471 As in example 5, let's say you accidentally commit some unrelated
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
472 changes together. Unlike example 5, you don't notice your mistake
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
473 immediately, but commit a new changeset on top of the bad one. ::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
474
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
475 $ echo 'this fixes bug 53' >> file1.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
476 $ echo 'debug hack' >> file2.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
477 $ hg commit -m 'fix bug 53' # rev 22 (oops)
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
478 $ echo 'and this handles bug 67' >> file1.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
479 $ hg commit -m 'fix bug 67' # rev 23 (fine)
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
480
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
481 As with ``amend``, you need to travel back in time and repair revision
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
482 22, leaving your changes to ``file2.c`` back in the working
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
483 directory::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
484
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
485 $ hg update 22
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
486 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
487 $ hg uncommit file2.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
488 1 new unstable changesets
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
489 $ hg status
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
490 M file2.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
491
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
492 Now your repository has unstable changesets, so you need to evolve it.
2931
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
493 However, ``hg evolve`` requires a clean working directory to resolve merge
978
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
494 conflicts, so you need to decide what to do with ``file2.c``.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
495
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
496 In this case, the change to ``file2.c`` was a temporary debugging
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
497 hack, so we can discard it and immediately evolve the instability away::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
498
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
499 $ hg revert file2.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
500 $ hg evolve --all
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
501 move:[23] fix bug 67
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
502 atop:[24] fix bug 53
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
503
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
504 Figure 10 illustrates the whole process.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
505
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
506 .. figure:: figures/figure-ug10.svg
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
507
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
508 Figure 10: ``hg uncommit`` of a changeset with descendants results
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
509 in instability *and* a dirty working directory, both of which must
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
510 be dealt with.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
511
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
512
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
513 Example 10: Uncommit files to an older changeset (keep changes)
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
514 ===================================================================
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
515
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
516 This is very similar to example 9. The difference that this time, our
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
517 change to ``file2.c`` is valuable enough to commit, making things a
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
518 bit more complicated. The setup is nearly identical::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
519
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
520 $ echo 'fix a bug' >> file1.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
521 $ echo 'useful but unrelated' >> file2.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
522 $ hg commit -u dan -d '11 0' -m 'fix a bug' # rev 26 (oops)
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
523 $ echo 'new feature' >> file1.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
524 $ hg commit -u dan -d '12 0' -m 'new feature' # rev 27 (fine)
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
525
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
526 As before, we update back to the flawed changeset (this time,
2931
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
527 revision 26) and use ``uncommit``, leaving uncommitted changes to
978
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
528 ``file2.c`` in the working dir::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
529
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
530 $ hg update -q 26
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
531 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
2931
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
532 $ hg uncommit -q file2.c # obsoletes rev 26, creates rev 28
978
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
533 1 new unstable changesets
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
534 $ hg status
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
535 M file2.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
536
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
537 This time, let's save that useful change before evolving::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
538
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
539 $ hg commit -m 'useful tweak' # rev 29
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
540
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
541 Figure 11 shows the story so far: ``uncommit`` obsoleted revision 26
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
542 and created revision 28, the successor of 26. Then we committed
2931
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
543 revision 29, a child of 28. We still have to deal with the revision 27,
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
544 which is an unstable changeset.
978
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
545
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
546 .. figure:: figures/figure-ug11.svg
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
547
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
548 Figure 11: Uncommitting a file and then committing that change
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
549 separately will soon result in a two-headed repository.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
550
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
551 This is where things get tricky. As usual when a repository has
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
552 unstable changesets, we want to evolve it::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
553
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
554 $ hg evolve --all
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
555
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
556 The problem is that ``hg evolve`` rebases revision 27 onto revision
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
557 28, creating 30 (the successor of 27). This is entirely logical: 27
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
558 was the child of 26, and 26's successor is 28. So of course 27's
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
559 successor (30) should be the child of 26's successor (28).
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
560 Unfortunately, that leaves us with a two-headed repository:
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
561
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
562 .. figure:: figures/figure-ug12.svg
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
563
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
564 Figure 12: ``evolve`` takes care of unstable changesets; it does
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
565 not solve all the world's problems.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
566
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
567 As usual when faced with a two-headed repository, you can either merge
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
568 or rebase. It's up to you.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
569
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
570
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
571 Example 11: Recover an obsolete changeset
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
572 =========================================
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
573
1270
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
574 Sometimes you might obsolete a changeset, and then change your mind. You'll
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
575 probably start looking for an “unobsolete” command to restore a changeset
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
576 to normal state. For complicated implementation reasons, that command
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
577 doesn't exist. (If you have already pushed an obsolescence marker to
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
578 another repo, then Mercurial would need a way to revoke that remote
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
579 obsolesence marker. That's a hard problem.)
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
580
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
581 Instead, ``evolve`` provides a ``touch`` command to resurrect an
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
582 obsolete changeset. An unexpected quirk: you almost certainly need to
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
583 use ``--hidden``, since obsolete changesets tend to be hidden, and you
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
584 can't reference a hidden changeset otherwise. Typical usage thus looks
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
585 like ::
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
586
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
587 $ hg --hidden touch REV
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
588
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
589 This creates a new, normal changeset which is the same as ``REV``—except
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
590 with a different changeset ID. The new changeset will have the same parent
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
591 as ``REV``, and will be a successor of ``REV``.
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
592
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
593 The current implementation of ``hg touch`` is not ideal, and is likely to
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
594 change in the future. Consider the history in Figure 12, where revision 27
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
595 is obsolete and the child of 26, also obsolete. If we ``hg touch 27``, that
2931
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
596 creates a new revision which is a non-obsolete child of 26—i.e., it is an
1270
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
597 unstable. It's also *divergent*, another type of trouble that we'll learn
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
598 about in the `next section`_.
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
599
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
600 .. _`next section`: sharing.html