docs/user-guide.rst
branchstable
changeset 1267 8cc6e90354a9
parent 978 8328337d23b2
child 1268 ba3ff8c00304
equal deleted inserted replaced
1266:c94aaf6df69c 1267:8cc6e90354a9
   203 *squash* or *collapse*.)
   203 *squash* or *collapse*.)
   204 
   204 
   205 Changeset obsolescence under the hood
   205 Changeset obsolescence under the hood
   206 -------------------------------------
   206 -------------------------------------
   207 
   207 
   208 So far, everything has gone just fine. We haven't run into merge
   208 So far, everything has gone just fine: we haven't run into merge
   209 conflicts or other trouble. Before we start exploring advanced usage
   209 conflicts or other trouble. Before we start exploring advanced usage
   210 that can run into trouble, let's step back and see what happens when
   210 that can run into trouble, let's step back and see what happens when
   211 Mercurial marks changesets obsolete. That will make it much easier to
   211 Mercurial marks changesets obsolete. That will make it much easier to
   212 understand the more advanced use cases we'll see later.
   212 understand the more advanced use cases we'll see later.
   213 
   213 
   215 modification uses the same underlying mechanism: the original
   215 modification uses the same underlying mechanism: the original
   216 changesets are marked *obsolete* and replaced by zero or more
   216 changesets are marked *obsolete* and replaced by zero or more
   217 *successors*. The obsolete changesets are the *precursors* of their
   217 *successors*. The obsolete changesets are the *precursors* of their
   218 successors. This applies equally to built-in commands (``commit
   218 successors. This applies equally to built-in commands (``commit
   219 --amend``), commands added by ``evolve`` (``amend``, ``prune``,
   219 --amend``), commands added by ``evolve`` (``amend``, ``prune``,
   220 ``uncommit``, ``fold``), and even commands provided by other
   220 ``uncommit``, ``fold``), and commands provided by other extensions
   221 extensions (``rebase``, ``histedit``).
   221 (``rebase``, ``histedit``).
   222 
   222 
   223 Another way of looking at it is that obsolescence is second-order
   223 Another way of looking at it is that obsolescence is second-order
   224 version control, i.e. the history of your history. We'll cover this in
   224 version control, i.e. the history of your history. We'll cover this in
   225 more detail (and mathematical precision) in the `concepts`_ guide.
   225 more detail (and mathematical precision) in the `concepts`_ guide.
   226 
   226 
   351 
   351 
   352 Example 7: Amend an older changeset
   352 Example 7: Amend an older changeset
   353 ===================================
   353 ===================================
   354 
   354 
   355 Sometimes you don't notice your mistakes until after you have
   355 Sometimes you don't notice your mistakes until after you have
   356 committed some new changesets on top of them. ::
   356 committed new changesets on top of them. ::
   357 
   357 
   358   $ hg commit -m 'fix bug 17'         # rev 11 (mistake here)
   358   $ hg commit -m 'fix bug 17'         # rev 11 (mistake here)
   359   $ hg commit -m 'cleanup'            # rev 12
   359   $ hg commit -m 'cleanup'            # rev 12
   360   $ hg commit -m 'feature 23'         # rev 13
   360   $ hg commit -m 'feature 23'         # rev 13
   361 
   361 
   362 Traditionally, your only option is to commit an "oops" changeset that
   362 Traditionally, your only option is to commit an "oops" changeset that
   363 fixes your mistake. That works, of course, but it makes you look bad:
   363 fixes your mistake. That works, of course, but it makes you look bad:
   364 you made a mistake, and the record of that mistake is recorded in
   364 you made a mistake, and the record of that mistake is recorded in
   365 history for all eternity. (If the mistake was in the commit message,
   365 history for all eternity. (If the mistake was in the commit message,
   366 too bad.)
   366 too bad: you cannot fix it.)
   367 
   367 
   368 More subtly, there now exist changesets that are *worse* than what
   368 More subtly, there now exist changesets that are *worse* than what
   369 came before—the code no longer builds, the tests don't pass, or
   369 came before—the code no longer builds, the tests don't pass, or
   370 similar. Anyone reviewing these patches will waste time noticing the
   370 similar. Anyone reviewing these patches will waste time on the error
   371 error in the earlier patch, and then the correction later on.
   371 in the earlier patch, and then the correction later on.
   372 
   372 
   373 You can avoid all this by amending the bad changeset and *evolving*
   373 You can avoid all this by amending the bad changeset and *evolving*
   374 subsequent history. Here's how it works, assuming you have just
   374 subsequent history. Here's how it works, assuming you have just
   375 committed revision 13 and noticed the mistake in revision 11::
   375 committed revision 13 and noticed the mistake in revision 11::
   376 
   376