# HG changeset patch # User Greg Ward # Date 1402020664 14400 # Node ID 8328337d23b20258fba70db9c4f7559094c2c3fd # Parent cc0f0d94bf30c8f6ab71324042571f135fcc0a5e docs: add new user guide This has also been reviewed to death on evolve-testers. There are still a couple of short sections to write (clearly marked "TODO"), and one example to add. But (if I may be so bold) this is a gigantic improvement over the current docs, so it really should get merged. Incidentally, the figures are all SVG files created with Inkscape. They're not perfect, but they're pretty nice. Anyone who knows a better way to create technical diagrams is welcome to contribute. One wart: there's a test script that accompanies the document and largely duplicates it, but I haven't unified them. I've been concentrating on writing the best possible content, not on fiddling with tools. I suspect that unifying them will be non-trivial, but definitely worth doing. diff -r cc0f0d94bf30 -r 8328337d23b2 docs/figures/figure-ug01.svg --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/figures/figure-ug01.svg Thu Jun 05 22:11:04 2014 -0400 @@ -0,0 +1,400 @@ + + + + diff -r cc0f0d94bf30 -r 8328337d23b2 docs/figures/figure-ug02.svg --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/figures/figure-ug02.svg Thu Jun 05 22:11:04 2014 -0400 @@ -0,0 +1,590 @@ + + + + diff -r cc0f0d94bf30 -r 8328337d23b2 docs/figures/figure-ug03.svg --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/figures/figure-ug03.svg Thu Jun 05 22:11:04 2014 -0400 @@ -0,0 +1,402 @@ + + + + diff -r cc0f0d94bf30 -r 8328337d23b2 docs/figures/figure-ug04.svg --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/figures/figure-ug04.svg Thu Jun 05 22:11:04 2014 -0400 @@ -0,0 +1,547 @@ + + + + diff -r cc0f0d94bf30 -r 8328337d23b2 docs/figures/figure-ug05.svg --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/figures/figure-ug05.svg Thu Jun 05 22:11:04 2014 -0400 @@ -0,0 +1,723 @@ + + + + diff -r cc0f0d94bf30 -r 8328337d23b2 docs/figures/figure-ug06.svg --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/figures/figure-ug06.svg Thu Jun 05 22:11:04 2014 -0400 @@ -0,0 +1,851 @@ + + + + diff -r cc0f0d94bf30 -r 8328337d23b2 docs/figures/figure-ug07.svg --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/figures/figure-ug07.svg Thu Jun 05 22:11:04 2014 -0400 @@ -0,0 +1,608 @@ + + + + diff -r cc0f0d94bf30 -r 8328337d23b2 docs/figures/figure-ug08.svg --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/figures/figure-ug08.svg Thu Jun 05 22:11:04 2014 -0400 @@ -0,0 +1,415 @@ + + + + diff -r cc0f0d94bf30 -r 8328337d23b2 docs/figures/figure-ug09.svg --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/figures/figure-ug09.svg Thu Jun 05 22:11:04 2014 -0400 @@ -0,0 +1,307 @@ + + + + diff -r cc0f0d94bf30 -r 8328337d23b2 docs/figures/figure-ug10.svg --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/figures/figure-ug10.svg Thu Jun 05 22:11:04 2014 -0400 @@ -0,0 +1,872 @@ + + + + diff -r cc0f0d94bf30 -r 8328337d23b2 docs/figures/figure-ug11.svg --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/figures/figure-ug11.svg Thu Jun 05 22:11:04 2014 -0400 @@ -0,0 +1,659 @@ + + + + diff -r cc0f0d94bf30 -r 8328337d23b2 docs/figures/figure-ug12.svg --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/figures/figure-ug12.svg Thu Jun 05 22:11:04 2014 -0400 @@ -0,0 +1,606 @@ + + + + diff -r cc0f0d94bf30 -r 8328337d23b2 docs/index.rst --- a/docs/index.rst Thu Jun 05 21:57:34 2014 -0400 +++ b/docs/index.rst Thu Jun 05 22:11:04 2014 -0400 @@ -93,7 +93,7 @@ Next steps: * For a practical guide to using ``evolve`` in a single repository, - see the `user guide`_ (coming soon). + see the `user guide`_. * For more advanced tricks, see `sharing mutable history`_ (coming soon). * To learn about the concepts underlying ``evolve``, see `concepts`_ (coming soon). diff -r cc0f0d94bf30 -r 8328337d23b2 docs/user-guide.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/user-guide.rst Thu Jun 05 22:11:04 2014 -0400 @@ -0,0 +1,561 @@ +.. Copyright © 2014 Greg Ward + +------------------ +Evolve: User Guide +------------------ + +.. contents:: + +Life without ``evolve`` +----------------------- + +Before we dive into learning about ``evolve``, let's look into some +features of core Mercurial that interact with ``evolve``. ``commit`` +affects ``evolve``, and ``evolve`` modifies how ``commit --amend`` +works. + +Example 1: Commit a new changeset +================================= + +To create a new changeset, simply run ``hg commit`` as usual. +``evolve`` does not change the behaviour of ``commit`` at all. + +However, it's important to understand that new changesets are in the +*draft* phase by default: they are mutable. This means that they can +be modified by Mercurial's existing history-editing commands +(``rebase``, ``histedit``, etc.), and also by the ``evolve`` +extension. Specifically, ``evolve`` adds a number of commands that can +be used to modify history: ``amend``, ``uncommit``, ``prune``, +``fold``, and ``evolve``. Generally speaking, changesets remain in +*draft* phase until they are pushed to another repository, at which +point they enter *public* phase. :: + + $ hg commit -m 'implement feature X' + $ hg phase -r . + 1: draft + +(Strictly speaking, changesets only become public when they are pushed +to a *publishing* repository. But all repositories are publishing by +default; you have to explicitly configure repositories to be +*non-publishing*. Non-publishing repositories are an advanced topic +which we'll see when we get to `sharing mutable history`_.) + +.. _`sharing mutable history`: sharing.html + +Example 2: Amend a changeset (traditional) +========================================== + +Imagine you've just committed a new changeset, and then you discover a +mistake. Maybe you forgot to run the tests and a failure slipped in. +You want to modify history so that you push one perfect changeset, +rather than one flawed changeset followed by an "oops" commit. (Or +perhaps you made a typo in the commit message—this is really feature +*Y*, not feature X. You can't fix that with a followup commit.) + +This is actually trivial with plain vanilla Mercurial since 2.2: fix +your mistake and run :: + + $ hg commit --amend -m 'implement feature Y' + +to create a new, amended changeset. The drawback of doing this with +vanilla Mercurial is that your original, flawed, changeset is removed +from the repository. This is *unsafe* history editing. It's probably +not too serious if all you did was fix a syntax error, but still. + +.. figure:: figures/figure-ug01.svg + + Figure 1: unsafe history modification with core Mercurial (not + using ``evolve``): the original revision 1 is destroyed. + +(Incidentally, Mercurial's traditional history modification mechanism +isn't *really* unsafe: any changeset(s) removed from the repository +are kept in a backup directory, so you can manually restore them later +if you change your mind. But it's awkward and inconvenient compared to +the features provided by ``evolve`` and changeset obsolescence.) + +Life with ``evolve`` (basic usage) +---------------------------------- + +Once you enable the ``evolve`` extension, a number of features are +available to you. First, we're going to explore several examples of +painless, trouble-free history modification. + +Example 3: Amend a changeset (with ``evolve``) +============================================== + +Outwardly, amending a changeset with ``evolve`` can look exactly the +same as it does with core Mercurial (example 2):: + + $ hg commit --amend -m 'implement feature Y' + +Alternately, you can use the new ``amend`` command added by +``evolve``:: + + $ hg amend -m 'implement feature Y' + +(``hg amend`` is nearly synonymous with ``hg commit --amend``. The +difference is that ``hg amend`` reuses the existing commit message by +default, whereas ``hg commit --amend`` runs your editor if you don't +pass ``-m`` or ``-l``.) + +Under the hood, though, things are quite different. Mercurial has +simply marked the old changeset *obsolete*, replacing it with a new +one. We'll explore what this means in detail later, after working +through a few more examples. + +Example 4: Prune an unwanted changeset +====================================== + +Sometimes you make a change, and then decide it was such a bad idea +that you don't want anyone to know about it. Or maybe it was a +debugging hack that you needed to keep around for a while, but do not +intend to ever push publicly. :: + + $ echo 'debug hack' >> file1.c + $ hg commit -m 'debug hack' + +In either case, ``hg prune`` is the answer. ``prune`` simply marks +changesets obsolete without creating any new changesets to replace +them:: + + $ hg prune . + 1 changesets pruned + 1 files updated, 0 files merged, 0 files removed, 0 files unresolved + working directory now at 934359450037 + +Outwardly, it appears that your “debug hack” commit never happened; +we're right back where we started:: + + $ hg parents --template '{rev}:{node|short} {desc|firstline}\n' + 3:934359450037 implement feature Y + +In reality, though, the “debug hack” is still there, obsolete and hidden. + +Example 5: Uncommit changes to certain files +============================================ + +Occasionally you commit more than you intended: perhaps you made +unrelated changes to different files, and thus intend to commit +different files separately. :: + + $ echo 'relevant' >> file1.c + $ echo 'irrelevant' >> file2.c + +If you forget to specify filenames on the ``commit`` command line, +Mercurial commits all those changes together:: + + $ hg commit -m 'fix bug 234' # oops: too many files + +Luckily, this mistake is easy to fix with ``uncommit``:: + + $ hg uncommit file2.c + $ hg status + M file2.c + +Let's verify that the replacement changeset looks right (i.e., +modifies only ``file1.c``):: + + $ hg parents --template '{rev}:{node|short} {desc|firstline}\n{files}\n' + 6:c8defeecf7a4 fix bug 234 + file1.c + +As before, the original flawed changeset is still there, but obsolete +and hidden. It won't be exchanged with other repositories by ``push``, +``pull``, or ``clone``. + +Example 6: Fold multiple changesets together into one +===================================================== + +If you're making extensive changes to fragile source code, you might +commit more frequently than normal so that you can fallback on a +known good state if one step goes badly. :: + + $ echo step1 >> file1.c + $ hg commit -m 'step 1' # revision 7 + $ echo step2 >> file1.c + $ hg commit -m 'step 2' # revision 8 + $ echo step3 >> file2.c + $ hg commit -m 'step 3' # revision 9 + +At the end of such a sequence, you often end up with a series of small +changesets that are tedious to review individually. It might make more +sense to combine them into a single changeset using the ``fold`` +command. + +To make sure we pass the right revisions to ``fold``, let's review the +changesets we just created, from revision 7:: + + $ hg log --template '{rev}:{node|short} {desc|firstline}\n' -r 7:: + 7:05e61aab8294 step 1 + 8:be6d5bc8e4cc step 2 + 9:35f432d9f7c1 step 3 + +and fold them:: + + $ hg fold -m 'fix bug 64' -r 7:: + 3 changesets folded + 1 files updated, 0 files merged, 0 files removed, 0 files unresolved + +This time, Mercurial marks three changesets obsolete, replacing them +all with a single *successor*. + +(You might be familiar with this operation under other names, like +*squash* or *collapse*.) + +Changeset obsolescence under the hood +------------------------------------- + +So far, everything has gone just fine. We haven't run into merge +conflicts or other trouble. Before we start exploring advanced usage +that can run into trouble, let's step back and see what happens when +Mercurial marks changesets obsolete. That will make it much easier to +understand the more advanced use cases we'll see later. + +When you have the ``evolve`` extension enabled, all history +modification uses the same underlying mechanism: the original +changesets are marked *obsolete* and replaced by zero or more +*successors*. The obsolete changesets are the *precursors* of their +successors. This applies equally to built-in commands (``commit +--amend``), commands added by ``evolve`` (``amend``, ``prune``, +``uncommit``, ``fold``), and even commands provided by other +extensions (``rebase``, ``histedit``). + +Another way of looking at it is that obsolescence is second-order +version control, i.e. the history of your history. We'll cover this in +more detail (and mathematical precision) in the `concepts`_ guide. + +.. _`concepts`: concepts.html + +Under the hood: Amend a changeset +================================= + +Consider Example 2, amending a changeset with ``evolve``. We saw above +that you can do this using the exact same command-line syntax as core +Mercurial, namely ``hg commit --amend``. But the implementation is +quite different, and Figure 2 shows how. + +.. figure:: figures/figure-ug02.svg + + Figure 2: safe history modification using ``evolve``: the original + revision 1 is preserved as an obsolete changeset. (The "temporary + amend commit", marked with T, is an implementation detail stemming + from limitations in Mercurial's current merge machinery. Future + versions of Mercurial will not create them.) + +In this case, the obsolete changesets are also *hidden*. That is the +usual end state for obsolete changesets. But many scenarios result in +obsolete changesets that are still visible, which indicates your +history modification work is not yet done. We'll see examples of that +later, when we cover advanced usage. + +Seeing hidden changesets +======================== + +TODO + +Under the hood: Prune an unwanted changeset +=========================================== + +``prune`` (example 4 above) is the simplest history modification +command provided by ``evolve``. All it does is mark the specified +changeset(s) obsolete, with no successor/precursor relationships +involved. (If the working directory parent was one of the obsolete +changesets, ``prune`` updates back to a suitable ancestor.) + +.. figure:: figures/figure-ug03.svg + + Figure 3: pruning a changeset marks it obsolete with no successors. + +Under the hood: Uncommit changes to certain files +================================================= + +In one sense, ``uncommit`` is a simplified version of ``amend``. Like +``amend``, it obsoletes one changeset and leaves it with a single +successor. Unlike ``amend``, there is no ugly "temporary amend commit" +cluttering up the repository. + +In another sense, ``uncommit`` is the inverse of ``amend``: ``amend`` +takes any uncommitted changes in the working dir and “adds” +them to the working directory's parent changeset. (In reality, of +course, it creates a successor changeset, marking the original +obsolete.) In contrast, ``uncommit`` takes some changes in the working +directory's parent and moves them to the working dir, creating a new +successor changeset in the process. Figure 4 illustrates. + +.. figure:: figures/figure-ug04.svg + + Figure 4: uncommit moves some of the changes from the working + directory parent into the working dir, preserving the remaining + changes as a new successor changeset. (N.B. revision 4 is not shown + here because it was marked obsolete in the previous example.) + + +Under the hood: Fold multiple changesets together into one +========================================================== + +The last basic example is folding multiple changesets into one, which +marks multiple changesets obsolete, replacing them all with a single +successor. + +.. figure:: figures/figure-ug05.svg + + Figure 5: fold combines multiple changesets into a single + successor, marking the original (folded) changesets obsolete. + + +Obsolete is not hidden +====================== + +TODO + + +Understanding revision numbers +============================== + +If you're trying these examples on your own, especially using ``hg +log`` without ``--hidden``, you have probably noticed some funny +business going on with revision numbers: there are now gaps in the +sequence. That's something you don't see with plain vanilla Mercurial; +normally, revision N is always followed by revision N+1. + +This is just the visible manifestation of hidden changesets. If +revision 95 is followed by revision 98, that means there are two +hidden changesets, 96 and 97, in between. + +Note that changeset IDs are still the permanent, immutable identifier +for changesets. Revision numbers are, as ever, a handy shorthand that +work in your local repository, but cannot be used across repositories. +They also have the useful property of showing when there are hidden +changesets lurking under the covers, which is why this document uses +revision numbers. + + +Life with ``evolve`` (advanced usage) +------------------------------------- + +Now that you've got a solid understanding of how ``evolve`` works in +concert with changeset obsolescence, let's explore some more advanced +scenarios. All of these scenarios will involve *unstable* changesets, +which is an unavoidable consequence of obsolescence. What really sets +``evolve`` apart from other history modification mechanisms is the +fact that it recognizes troubles like unstable changesets and provides +a consistent way for you to get out of trouble. + +(Incidentally, there are two other types of trouble that changesets +can get into with ``evolve``: they may be *divergent* or *bumped*. +Both of those states are more likely to occur when `sharing mutable +history`_, so we won't see them in this user guide.) + +.. _`sharing mutable history`: sharing.html + + +Example 7: Amend an older changeset +=================================== + +Sometimes you don't notice your mistakes until after you have +committed some new changesets on top of them. :: + + $ hg commit -m 'fix bug 17' # rev 11 (mistake here) + $ hg commit -m 'cleanup' # rev 12 + $ hg commit -m 'feature 23' # rev 13 + +Traditionally, your only option is to commit an "oops" changeset that +fixes your mistake. That works, of course, but it makes you look bad: +you made a mistake, and the record of that mistake is recorded in +history for all eternity. (If the mistake was in the commit message, +too bad.) + +More subtly, there now exist changesets that are *worse* than what +came before—the code no longer builds, the tests don't pass, or +similar. Anyone reviewing these patches will waste time noticing the +error in the earlier patch, and then the correction later on. + +You can avoid all this by amending the bad changeset and *evolving* +subsequent history. Here's how it works, assuming you have just +committed revision 13 and noticed the mistake in revision 11:: + + $ hg update 11 + [...fix mistake...] + $ hg amend + +At this point, revision 11 is *obsolete* and revisions 12 and 13—the +descendants of 11—are in a funny state: they are *unstable*. + +.. figure:: figures/figure-ug06.svg + + Figure 6: amending a changeset with descendants means the amended + changeset is obsolete but remains visible; its non-obsolete + descendants are *unstable*. The temporary amend commit, revision + 14, is hidden because it has no non-obsolete descendants. + +All non-obsolete descendants of an obsolete changeset are unstable. An +interesting consequence of this is that revision 11 is still visible, +even though it is obsolete. Obsolete changesets with non-obsolete +descendants are not hidden. + +The fix is to *evolve* history:: + + $ hg evolve --all + +This is a separate step, not automatically part of ``hg amend``, +because there might be conflicts. If your amended changeset modifies a +file that one of its descendants also modified, Mercurial has to fire +up your merge tool to resolve the conflict. More importantly, you have +to switch contexts from "writing code" to "resolving conflicts". That +can be an expensive context switch, so Mercurial lets you decide when +to do it. + +The end state, after ``evolve`` finishes, is that the original +revisions (11-13) are obsolete and hidden. Their successor revisions +(15-17) replace them. + +.. figure:: figures/figure-ug07.svg + + Figure 7: evolve your repository (``hg evolve --all``) to take care + of instability. Unstable changesets become obsolete, and are + replaced by successors just like the amended changeset was. + +Example 8: Prune an older changeset +=================================== + +Let's say you've just committed the following changesets:: + + $ hg commit -m 'useful work' # rev 18 + $ hg commit -m 'debug hack' # rev 19 + $ hg commit -m 'more work' # rev 20 + +You want to drop revision 19, but keep 18 and 20. No problem:: + + $ hg prune 19 + 1 changesets pruned + 1 new unstable changesets + +As above, this leaves your repository in a funny intermediate state: +revision 20 is the non-obsolete descendant of obsolete revision 19. +That is, revision 20 is unstable. + +.. figure:: figures/figure-ug08.svg + + Figure 8: ``hg prune`` marks a changeset obsolete without creating + a successor. Just like with ``hg amend``, non-obsolete descendants + of the pruned changeset are now unstable. + +As before, the solution to unstable changesets is to evolve your +repository:: + + $ hg evolve --all + +This rebases revision 20 on top of 18 as the new revision 21, leaving +19 and 20 obsolete and hidden: + +.. figure:: figures/figure-ug09.svg + + Figure 9: once again, ``hg evolve --all`` takes care of instability. + +Example 9: Uncommit files from an older changeset (discard changes) +======================================================================= + +As in example 5, let's say you accidentally commit some unrelated +changes together. Unlike example 5, you don't notice your mistake +immediately, but commit a new changeset on top of the bad one. :: + + $ echo 'this fixes bug 53' >> file1.c + $ echo 'debug hack' >> file2.c + $ hg commit -m 'fix bug 53' # rev 22 (oops) + $ echo 'and this handles bug 67' >> file1.c + $ hg commit -m 'fix bug 67' # rev 23 (fine) + +As with ``amend``, you need to travel back in time and repair revision +22, leaving your changes to ``file2.c`` back in the working +directory:: + + $ hg update 22 + 1 files updated, 0 files merged, 0 files removed, 0 files unresolved + $ hg uncommit file2.c + 1 new unstable changesets + $ hg status + M file2.c + +Now your repository has unstable changesets, so you need to evolve it. +But ``hg evolve`` requires a clean working directory to resolve merge +conflicts, so you need to decide what to do with ``file2.c``. + +In this case, the change to ``file2.c`` was a temporary debugging +hack, so we can discard it and immediately evolve the instability away:: + + $ hg revert file2.c + $ hg evolve --all + move:[23] fix bug 67 + atop:[24] fix bug 53 + +Figure 10 illustrates the whole process. + +.. figure:: figures/figure-ug10.svg + + Figure 10: ``hg uncommit`` of a changeset with descendants results + in instability *and* a dirty working directory, both of which must + be dealt with. + + +Example 10: Uncommit files to an older changeset (keep changes) +=================================================================== + +This is very similar to example 9. The difference that this time, our +change to ``file2.c`` is valuable enough to commit, making things a +bit more complicated. The setup is nearly identical:: + + $ echo 'fix a bug' >> file1.c + $ echo 'useful but unrelated' >> file2.c + $ hg commit -u dan -d '11 0' -m 'fix a bug' # rev 26 (oops) + $ echo 'new feature' >> file1.c + $ hg commit -u dan -d '12 0' -m 'new feature' # rev 27 (fine) + +As before, we update back to the flawed changeset (this time, +revision 26) and ``uncommit``, leaving uncommitted changes to +``file2.c`` in the working dir:: + + $ hg update -q 26 + 1 files updated, 0 files merged, 0 files removed, 0 files unresolved + $ hg uncommit -q file2.c # obsoletes rev 26, creates rev 28 + 1 new unstable changesets + $ hg status + M file2.c + +This time, let's save that useful change before evolving:: + + $ hg commit -m 'useful tweak' # rev 29 + +Figure 11 shows the story so far: ``uncommit`` obsoleted revision 26 +and created revision 28, the successor of 26. Then we committed +revision 29, a child of 28. We still have to deal with the unstable +revision 27. + +.. figure:: figures/figure-ug11.svg + + Figure 11: Uncommitting a file and then committing that change + separately will soon result in a two-headed repository. + +This is where things get tricky. As usual when a repository has +unstable changesets, we want to evolve it:: + + $ hg evolve --all + +The problem is that ``hg evolve`` rebases revision 27 onto revision +28, creating 30 (the successor of 27). This is entirely logical: 27 +was the child of 26, and 26's successor is 28. So of course 27's +successor (30) should be the child of 26's successor (28). +Unfortunately, that leaves us with a two-headed repository: + +.. figure:: figures/figure-ug12.svg + + Figure 12: ``evolve`` takes care of unstable changesets; it does + not solve all the world's problems. + +As usual when faced with a two-headed repository, you can either merge +or rebase. It's up to you. + + +Example 11: Recover an obsolete changeset +========================================= + +TODO diff -r cc0f0d94bf30 -r 8328337d23b2 tests/test-userguide.t --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/tests/test-userguide.t Thu Jun 05 22:11:04 2014 -0400 @@ -0,0 +1,316 @@ +ensure that all the scenarios in the user guide work as documented + +basic repo + $ hg init t + $ cd t + $ touch file1.c file2.c + $ hg -q commit -A -m init + +example 1: commit creates a changeset in draft phase +(this is nothing to do with evolve, but it's mentioned in the user guide) + $ echo 'feature Y' >> file1.c + $ hg commit -u alice -d '0 0' -m 'implement feature X' + $ hg phase -r . + 1: draft + $ hg identify -in + 6e725fd2be6f 1 + +example 2: unsafe amend with plain vanilla Mercurial: the original +commit is stripped + $ hg commit --amend -u alice -d '1 0' -m 'implement feature Y' + saved backup bundle to $TESTTMP/t/.hg/strip-backup/6e725fd2be6f-amend-backup.hg + $ hg log -r 23fe4ac6d3f1 + abort: unknown revision '23fe4ac6d3f1'! + [255] + $ hg identify -in + fe0ecd3bd2a4 1 + +enable evolve for safe history modification + $ cat >> $HGRCPATH < [alias] + > shortlog = log --template '{rev}:{node|short} {phase} {desc|firstline}\n' + > [extensions] + > rebase = + > EOF + $ echo "evolve=$(echo $(dirname $TESTDIR))/hgext/evolve.py" >> $HGRCPATH + +example 3: safe amend with "hg commit --amend" (figure 2) + $ echo 'tweak feature Y' >> file1.c + $ hg commit --amend -u alice -d '2 0' -m 'implement feature Y' + $ hg shortlog -q -r fe0ecd3bd2a4 + abort: unknown revision 'fe0ecd3bd2a4'! + [255] + $ hg --hidden shortlog -G + @ 3:934359450037 draft implement feature Y + | + | x 2:6c5f78d5d467 draft temporary amend commit for fe0ecd3bd2a4 + | | + | x 1:fe0ecd3bd2a4 draft implement feature Y + |/ + o 0:08c4b6f4efc8 draft init + +example 3 redux: repeat safe amend, this time with "hg amend" + $ hg rollback -q + $ hg amend -u alice -d '2 0' -m 'implement feature Y' + $ hg --hidden shortlog -G + @ 3:934359450037 draft implement feature Y + | + | x 2:6c5f78d5d467 draft temporary amend commit for fe0ecd3bd2a4 + | | + | x 1:fe0ecd3bd2a4 draft implement feature Y + |/ + o 0:08c4b6f4efc8 draft init + +example 4: prune at head (figure 3) + $ echo 'debug hack' >> file1.c + $ hg commit -m 'debug hack' + $ hg prune . + 1 changesets pruned + 1 files updated, 0 files merged, 0 files removed, 0 files unresolved + working directory now at 934359450037 + $ hg parents --template '{rev}:{node|short} {desc|firstline}\n' + 3:934359450037 implement feature Y + $ hg --hidden shortlog -G -r 3: + x 4:a3e0ef24aaf0 draft debug hack + | + @ 3:934359450037 draft implement feature Y + | + +example 5: uncommit files at head (figure 4) + $ echo 'relevant' >> file1.c + $ echo 'irrelevant' >> file2.c + $ hg commit -u dan -d '10 0' -m 'fix bug 234' + $ hg uncommit file2.c + $ hg status + M file2.c + $ hg --hidden shortlog -G -r 'descendants(3) - 4' + @ 6:c8defeecf7a4 draft fix bug 234 + | + | x 5:da4331967f5f draft fix bug 234 + |/ + o 3:934359450037 draft implement feature Y + | + $ hg parents --template '{rev}:{node|short} {desc|firstline}\n{files}\n' + 6:c8defeecf7a4 fix bug 234 + file1.c + $ hg revert --no-backup file2.c + +example 6: fold multiple changesets together into one (figure 5) + $ echo step1 >> file1.c + $ hg commit -m 'step 1' + $ echo step2 >> file1.c + $ hg commit -m 'step 2' + $ echo step3 >> file2.c + $ hg commit -m 'step 3' + $ hg log --template '{rev}:{node|short} {desc|firstline}\n' -r 7:: + 7:05e61aab8294 step 1 + 8:be6d5bc8e4cc step 2 + 9:35f432d9f7c1 step 3 + $ hg fold -d '0 0' -m 'fix bug 64' -r 7:: + 3 changesets folded + 1 files updated, 0 files merged, 0 files removed, 0 files unresolved + $ hg --hidden shortlog -G -r 6:: + @ 10:171c6a79a27b draft fix bug 64 + | + | x 9:35f432d9f7c1 draft step 3 + | | + | x 8:be6d5bc8e4cc draft step 2 + | | + | x 7:05e61aab8294 draft step 1 + |/ + o 6:c8defeecf7a4 draft fix bug 234 + | + $ hg --hidden log -q -r 'successors(7) | successors(8) | successors(9)' + 10:171c6a79a27b + $ hg --hidden log -q -r 'precursors(10)' + 7:05e61aab8294 + 8:be6d5bc8e4cc + 9:35f432d9f7c1 + $ hg diff -c 10 -U 0 + diff -r c8defeecf7a4 -r 171c6a79a27b file1.c + --- a/file1.c Thu Jan 01 00:00:10 1970 +0000 + +++ b/file1.c Thu Jan 01 00:00:00 1970 +0000 + @@ -3,0 +4,2 @@ + +step1 + +step2 + diff -r c8defeecf7a4 -r 171c6a79a27b file2.c + --- a/file2.c Thu Jan 01 00:00:10 1970 +0000 + +++ b/file2.c Thu Jan 01 00:00:00 1970 +0000 + @@ -0,0 +1,1 @@ + +step3 + +setup for example 7: amend an older changeset + $ echo 'fix fix oops fix' > file2.c + $ hg commit -u bob -d '3 0' -m 'fix bug 17' + $ echo 'cleanup' >> file1.c + $ hg commit -u bob -d '4 0' -m 'cleanup' + $ echo 'new feature' >> file1.c + $ hg commit -u bob -d '5 0' -m 'feature 23' + $ hg --hidden shortlog -G -r 10:: + @ 13:dadcbba2d606 draft feature 23 + | + o 12:debd46bb29dc draft cleanup + | + o 11:3e1cb8f70c02 draft fix bug 17 + | + o 10:171c6a79a27b draft fix bug 64 + | + +example 7: amend an older changeset (figures 6, 7) + $ hg update -q 11 + $ echo 'fix fix fix fix' > file2.c + $ hg amend -u bob -d '6 0' + 2 new unstable changesets + $ hg shortlog -r 'obsolete()' + 11:3e1cb8f70c02 draft fix bug 17 + $ hg shortlog -r 'unstable()' + 12:debd46bb29dc draft cleanup + 13:dadcbba2d606 draft feature 23 + $ hg --hidden shortlog -G -r 10:: + @ 15:395cbeda3a06 draft fix bug 17 + | + | x 14:f7fab707e247 draft temporary amend commit for 3e1cb8f70c02 + | | + | | o 13:dadcbba2d606 draft feature 23 + | | | + | | o 12:debd46bb29dc draft cleanup + | |/ + | x 11:3e1cb8f70c02 draft fix bug 17 + |/ + o 10:171c6a79a27b draft fix bug 64 + | + $ hg evolve -q --all + $ hg shortlog -G -r 10:: + @ 17:91b4b0f8b5c5 draft feature 23 + | + o 16:fe8858bd9bc2 draft cleanup + | + o 15:395cbeda3a06 draft fix bug 17 + | + o 10:171c6a79a27b draft fix bug 64 + | + +setup for example 8: prune an older changeset (figure 8) + $ echo 'useful' >> file1.c + $ hg commit -u carl -d '7 0' -m 'useful work' + $ echo 'debug' >> file2.c + $ hg commit -u carl -d '8 0' -m 'debug hack' + $ echo 'more useful' >> file1.c + $ hg commit -u carl -d '9 0' -m 'more work' + $ hg shortlog -G -r 17:: + @ 20:ea8fafca914b draft more work + | + o 19:b23d06b457a8 draft debug hack + | + o 18:1f33e68b18b9 draft useful work + | + o 17:91b4b0f8b5c5 draft feature 23 + | + +example 8: prune an older changeset (figures 8, 9) + $ hg prune 19 + 1 changesets pruned + 1 new unstable changesets + $ hg --hidden shortlog -G -r 18:: + @ 20:ea8fafca914b draft more work + | + x 19:b23d06b457a8 draft debug hack + | + o 18:1f33e68b18b9 draft useful work + | + $ hg evolve -q --all + $ hg --hidden shortlog -G -r 18:: + @ 21:4393e5877437 draft more work + | + | x 20:ea8fafca914b draft more work + | | + | x 19:b23d06b457a8 draft debug hack + |/ + o 18:1f33e68b18b9 draft useful work + | + +example 9: uncommit files from an older changeset (discard changes) +(figure 10) + $ echo 'this fixes bug 53' >> file1.c + $ echo 'debug hack' >> file2.c + $ hg commit -u dan -d '11 0' -m 'fix bug 53' + $ echo 'and this handles bug 67' >> file1.c + $ hg commit -u dan -d '12 0' -m 'fix bug 67' + $ hg update 22 + 1 files updated, 0 files merged, 0 files removed, 0 files unresolved + $ hg shortlog -G -r 21:: + o 23:4db2428c8ae3 draft fix bug 67 + | + @ 22:f84357446753 draft fix bug 53 + | + o 21:4393e5877437 draft more work + | + $ hg uncommit file2.c + 1 new unstable changesets + $ hg status + M file2.c + $ hg revert file2.c + $ hg evolve --all + move:[23] fix bug 67 + atop:[24] fix bug 53 + $ hg --hidden shortlog -G -r 21:: + @ 25:0d972d6888e6 draft fix bug 67 + | + o 24:71bb83d674c5 draft fix bug 53 + | + | x 23:4db2428c8ae3 draft fix bug 67 + | | + | x 22:f84357446753 draft fix bug 53 + |/ + o 21:4393e5877437 draft more work + | + $ rm file2.c.orig + +example 10: uncommit files from an older changeset (keep changes) +(figures 11, 12) + $ echo 'fix a bug' >> file1.c + $ echo 'useful but unrelated' >> file2.c + $ hg commit -u dan -d '11 0' -m 'fix a bug' + $ echo 'new feature' >> file1.c + $ hg commit -u dan -d '12 0' -m 'new feature' + $ hg update 26 + 1 files updated, 0 files merged, 0 files removed, 0 files unresolved + $ hg --hidden shortlog -G -r 25:: + o 27:fbb3c6d50427 draft new feature + | + @ 26:5b31a1239ab9 draft fix a bug + | + o 25:0d972d6888e6 draft fix bug 67 + | + $ hg uncommit file2.c + 1 new unstable changesets + $ hg status + M file2.c + $ hg commit -m 'useful tweak' + $ hg --hidden shortlog -G -r 25:: + @ 29:51e0d8c0a922 draft useful tweak + | + o 28:2594e98553a9 draft fix a bug + | + | o 27:fbb3c6d50427 draft new feature + | | + | x 26:5b31a1239ab9 draft fix a bug + |/ + o 25:0d972d6888e6 draft fix bug 67 + | + $ hg evolve --all + move:[27] new feature + atop:[28] fix a bug + $ hg --hidden shortlog -G -r 25:: + @ 30:166c1c368ab6 draft new feature + | + | o 29:51e0d8c0a922 draft useful tweak + |/ + o 28:2594e98553a9 draft fix a bug + | + | x 27:fbb3c6d50427 draft new feature + | | + | x 26:5b31a1239ab9 draft fix a bug + |/ + o 25:0d972d6888e6 draft fix bug 67 + |