docs/user-guide.rst
author Pierre-Yves David <pierre-yves.david@fb.com>
Fri, 06 Feb 2015 17:01:28 +0000
branchstable
changeset 1202 4099b087f672
parent 978 8328337d23b2
child 1267 8cc6e90354a9
permissions -rw-r--r--
evolve: handle invalid obsmarkers in the `debugobsconvert` User can now recover from such situation, The error message is also changed to point the `debugobsconvert` commands.
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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``,
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    29
``fold``, and ``evolve``. Generally speaking, changesets remain in
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    30
*draft* phase until they are pushed to another repository, at which
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    31
point they enter *public* phase. ::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    32
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    33
  $ hg commit -m 'implement feature X'
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    34
  $ hg phase -r .
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    35
  1: draft
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    36
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    37
(Strictly speaking, changesets only become public when they are pushed
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    38
to a *publishing* repository. But all repositories are publishing by
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    39
default; you have to explicitly configure repositories to be
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
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    63
not too serious if all you did was fix a syntax error, but still.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    64
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    65
.. figure:: figures/figure-ug01.svg
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    66
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    67
   Figure 1: unsafe history modification with core Mercurial (not
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    68
   using ``evolve``): the original revision 1 is destroyed.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    69
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    70
(Incidentally, Mercurial's traditional history modification mechanism
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    71
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
    72
are kept in a backup directory, so you can manually restore them later
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    73
if you change your mind. But it's awkward and inconvenient compared to
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    74
the features provided by ``evolve`` and changeset obsolescence.)
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    75
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    76
Life with ``evolve`` (basic usage)
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
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    79
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
    80
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
    81
painless, trouble-free history modification.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    82
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    83
Example 3: Amend a changeset (with ``evolve``)
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
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    86
Outwardly, amending a changeset with ``evolve`` can look exactly the
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    87
same as it does with core Mercurial (example 2)::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    88
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    89
  $ hg commit --amend -m 'implement feature Y'
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
Alternately, you can use the new ``amend`` command added by
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    92
``evolve``::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    93
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    94
  $ hg amend -m 'implement feature Y'
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`` is nearly synonymous with ``hg commit --amend``. The
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    97
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
    98
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
    99
pass ``-m`` or ``-l``.)
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   100
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   101
Under the hood, though, things are quite different. Mercurial has
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   102
simply marked the old changeset *obsolete*, replacing it with a new
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   103
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
   104
through a few more examples.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   105
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   106
Example 4: Prune an unwanted changeset
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
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   109
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
   110
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
   111
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
   112
intend to ever push publicly. ::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   113
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   114
  $ echo 'debug hack' >> file1.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   115
  $ hg commit -m 'debug hack'
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   116
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   117
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
   118
changesets obsolete without creating any new changesets to replace
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   119
them::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   120
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   121
  $ hg prune .
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   122
  1 changesets pruned
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   123
  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
   124
  working directory now at 934359450037
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   125
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   126
Outwardly, it appears that your “debug hack” commit never happened;
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   127
we're right back where we started::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   128
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   129
  $ hg parents --template '{rev}:{node|short}  {desc|firstline}\n'
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   130
  3:934359450037  implement feature Y
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   131
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   132
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
   133
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   134
Example 5: Uncommit changes to certain files
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
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   137
Occasionally you commit more than you intended: perhaps you made
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   138
unrelated changes to different files, and thus intend to commit
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   139
different files separately. ::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   140
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   141
  $ echo 'relevant' >> file1.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   142
  $ echo 'irrelevant' >> file2.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   143
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   144
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
   145
Mercurial commits all those changes together::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   146
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   147
  $ hg commit -m 'fix bug 234'          # oops: too many files
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
Luckily, this mistake is easy to fix with ``uncommit``::
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
  $ hg uncommit file2.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   152
  $ hg status
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   153
  M file2.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   154
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   155
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
   156
modifies only ``file1.c``)::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   157
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   158
  $ 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
   159
  6:c8defeecf7a4  fix bug 234
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   160
  file1.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   161
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   162
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
   163
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
   164
``pull``, or ``clone``.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   165
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   166
Example 6: Fold multiple changesets together into one
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
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   169
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
   170
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
   171
known good state if one step goes badly. ::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   172
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   173
  $ echo step1 >> file1.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   174
  $ hg commit -m 'step 1'               # revision 7
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   175
  $ echo step2 >> file1.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   176
  $ hg commit -m 'step 2'               # revision 8
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   177
  $ echo step3 >> file2.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   178
  $ hg commit -m 'step 3'               # revision 9
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   179
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   180
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
   181
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
   182
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
   183
command.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   184
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   185
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
   186
changesets we just created, from revision 7::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   187
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   188
  $ 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
   189
  7:05e61aab8294  step 1
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   190
  8:be6d5bc8e4cc  step 2
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   191
  9:35f432d9f7c1  step 3
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   192
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   193
and fold them::
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
  $ hg fold -m 'fix bug 64' -r 7::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   196
  3 changesets folded
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   197
  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
   198
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   199
This time, Mercurial marks three changesets obsolete, replacing them
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   200
all with a single *successor*.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   201
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   202
(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
   203
*squash* or *collapse*.)
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   204
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   205
Changeset obsolescence under the hood
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
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   208
So far, everything has gone just fine. We haven't run into merge
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   209
conflicts or other trouble. Before we start exploring advanced usage
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   210
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
   211
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
   212
understand the more advanced use cases we'll see later.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   213
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   214
When you have the ``evolve`` extension enabled, all history
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   215
modification uses the same underlying mechanism: the original
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   216
changesets are marked *obsolete* and replaced by zero or more
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   217
*successors*. The obsolete changesets are the *precursors* of their
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   218
successors. This applies equally to built-in commands (``commit
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   219
--amend``), commands added by ``evolve`` (``amend``, ``prune``,
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   220
``uncommit``, ``fold``), and even commands provided by other
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   221
extensions (``rebase``, ``histedit``).
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   222
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   223
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
   224
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
   225
more detail (and mathematical precision) in the `concepts`_ guide.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   226
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   227
.. _`concepts`: concepts.html
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
Under the hood: Amend a changeset
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
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   232
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
   233
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
   234
Mercurial, namely ``hg commit --amend``. But the implementation is
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   235
quite different, and Figure 2 shows how.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   236
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   237
.. figure:: figures/figure-ug02.svg
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 2: safe history modification using ``evolve``: the original
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   240
   revision 1 is preserved as an obsolete changeset. (The "temporary
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   241
   amend commit", marked with T, is an implementation detail stemming
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   242
   from limitations in Mercurial's current merge machinery. Future
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   243
   versions of Mercurial will not create them.)
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   244
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   245
In this case, the obsolete changesets are also *hidden*. That is the
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   246
usual end state for obsolete changesets. But many scenarios result in
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   247
obsolete changesets that are still visible, which indicates your
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   248
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
   249
later, when we cover advanced usage.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   250
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   251
Seeing hidden changesets
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   252
========================
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   253
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   254
TODO
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   255
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   256
Under the hood: Prune an unwanted changeset
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   257
===========================================
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   258
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   259
``prune`` (example 4 above) is the simplest history modification
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   260
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
   261
changeset(s) obsolete, with no successor/precursor relationships
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   262
involved. (If the working directory parent was one of the obsolete
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   263
changesets, ``prune`` updates back to a suitable ancestor.)
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   264
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   265
.. figure:: figures/figure-ug03.svg
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   266
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   267
   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
   268
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   269
Under the hood: Uncommit changes to certain files
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   270
=================================================
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   271
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   272
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
   273
``amend``, it obsoletes one changeset and leaves it with a single
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   274
successor. Unlike ``amend``, there is no ugly "temporary amend commit"
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   275
cluttering up the repository.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   276
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   277
In another sense, ``uncommit`` is the inverse of ``amend``: ``amend``
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   278
takes any uncommitted changes in the working dir and “adds”
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   279
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
   280
course, it creates a successor changeset, marking the original
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   281
obsolete.) In contrast, ``uncommit`` takes some changes in the working
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   282
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
   283
successor changeset in the process. Figure 4 illustrates.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   284
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   285
.. figure:: figures/figure-ug04.svg
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   286
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   287
   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
   288
   directory parent into the working dir, preserving the remaining
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   289
   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
   290
   here because it was marked obsolete in the previous example.)
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   291
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   292
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   293
Under the hood: Fold multiple changesets together into one
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
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   296
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
   297
marks multiple changesets obsolete, replacing them all with a single
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   298
successor.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   299
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   300
.. figure:: figures/figure-ug05.svg
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
   Figure 5: fold combines multiple changesets into a single
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   303
   successor, marking the original (folded) changesets obsolete.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   304
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   305
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   306
Obsolete is not hidden
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   307
======================
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   308
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   309
TODO
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   310
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
Understanding revision numbers
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
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   315
If you're trying these examples on your own, especially using ``hg
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   316
log`` without ``--hidden``, you have probably noticed some funny
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   317
business going on with revision numbers: there are now gaps in the
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   318
sequence. That's something you don't see with plain vanilla Mercurial;
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   319
normally, revision N is always followed by revision N+1.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   320
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   321
This is just the visible manifestation of hidden changesets. If
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   322
revision 95 is followed by revision 98, that means there are two
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   323
hidden changesets, 96 and 97, in between.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   324
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   325
Note that changeset IDs are still the permanent, immutable identifier
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   326
for changesets. Revision numbers are, as ever, a handy shorthand that
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   327
work in your local repository, but cannot be used across repositories.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   328
They also have the useful property of showing when there are hidden
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   329
changesets lurking under the covers, which is why this document uses
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   330
revision numbers.
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
Life with ``evolve`` (advanced usage)
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
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   336
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
   337
concert with changeset obsolescence, let's explore some more advanced
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   338
scenarios. All of these scenarios will involve *unstable* changesets,
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   339
which is an unavoidable consequence of obsolescence. What really sets
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   340
``evolve`` apart from other history modification mechanisms is the
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   341
fact that it recognizes troubles like unstable changesets and provides
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   342
a consistent way for you to get out of trouble.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   343
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   344
(Incidentally, there are two other types of trouble that changesets
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   345
can get into with ``evolve``: they may be *divergent* or *bumped*.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   346
Both of those states are more likely to occur when `sharing mutable
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   347
history`_, so we won't see them in this user guide.)
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
.. _`sharing mutable history`: sharing.html
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   350
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   351
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   352
Example 7: Amend an older changeset
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   353
===================================
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   354
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   355
Sometimes you don't notice your mistakes until after you have
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   356
committed some new changesets on top of them. ::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   357
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   358
  $ hg commit -m 'fix bug 17'         # rev 11 (mistake here)
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   359
  $ hg commit -m 'cleanup'            # rev 12
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   360
  $ hg commit -m 'feature 23'         # rev 13
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   361
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   362
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
   363
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
   364
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
   365
history for all eternity. (If the mistake was in the commit message,
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   366
too bad.)
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
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
   369
came before—the code no longer builds, the tests don't pass, or
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   370
similar. Anyone reviewing these patches will waste time noticing the
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   371
error in the earlier patch, and then the correction later on.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   372
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   373
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
   374
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
   375
committed revision 13 and noticed the mistake in revision 11::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   376
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   377
  $ hg update 11
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   378
  [...fix mistake...]
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   379
  $ hg amend
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   380
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   381
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
   382
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
   383
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   384
.. figure:: figures/figure-ug06.svg
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   385
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   386
   Figure 6: amending a changeset with descendants means the amended
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   387
   changeset is obsolete but remains visible; its non-obsolete
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   388
   descendants are *unstable*. The temporary amend commit, revision
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   389
   14, is hidden because it has no non-obsolete descendants.
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
All non-obsolete descendants of an obsolete changeset are unstable. An
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   392
interesting consequence of this is that revision 11 is still visible,
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   393
even though it is obsolete. Obsolete changesets with non-obsolete
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   394
descendants are not hidden.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   395
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   396
The fix is to *evolve* history::
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
  $ hg evolve --all
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
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
   401
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
   402
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
   403
up your merge tool to resolve the conflict. More importantly, you have
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   404
to switch contexts from "writing code" to "resolving conflicts". That
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   405
can be an expensive context switch, so Mercurial lets you decide when
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   406
to do it.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   407
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   408
The end state, after ``evolve`` finishes, is that the original
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   409
revisions (11-13) are obsolete and hidden. Their successor revisions
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   410
(15-17) replace them.
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
.. figure:: figures/figure-ug07.svg
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
   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
   415
   of instability. Unstable changesets become obsolete, and are
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   416
   replaced by successors just like the amended changeset was.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   417
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   418
Example 8: Prune an older changeset
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   419
===================================
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
Let's say you've just committed the following changesets::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   422
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   423
  $ hg commit -m 'useful work'       # rev 18
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   424
  $ hg commit -m 'debug hack'        # rev 19
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   425
  $ hg commit -m 'more work'         # rev 20
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
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
   428
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   429
  $ hg prune 19
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   430
  1 changesets pruned
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   431
  1 new unstable changesets
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
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
   434
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
   435
That is, revision 20 is unstable.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   436
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   437
.. figure:: figures/figure-ug08.svg
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   438
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   439
   Figure 8: ``hg prune`` marks a changeset obsolete without creating
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   440
   a successor. Just like with ``hg amend``, non-obsolete descendants
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   441
   of the pruned changeset are now unstable.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   442
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   443
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
   444
repository::
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
  $ hg evolve --all
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   447
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   448
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
   449
19 and 20 obsolete and hidden:
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   450
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   451
.. figure:: figures/figure-ug09.svg
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   452
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   453
   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
   454
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   455
Example 9: Uncommit files from an older changeset (discard changes)
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   456
=======================================================================
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   457
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   458
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
   459
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
   460
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
   461
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   462
  $ echo 'this fixes bug 53' >> file1.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   463
  $ echo 'debug hack' >> file2.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   464
  $ hg commit -m 'fix bug 53'                     # rev 22 (oops)
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   465
  $ echo 'and this handles bug 67' >> file1.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   466
  $ hg commit -m 'fix bug 67'                     # rev 23 (fine)
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
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
   469
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
   470
directory::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   471
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   472
  $ hg update 22
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   473
  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
   474
  $ hg uncommit file2.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   475
  1 new unstable changesets
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   476
  $ hg status
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   477
  M file2.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   478
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   479
Now your repository has unstable changesets, so you need to evolve it.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   480
But ``hg evolve`` requires a clean working directory to resolve merge
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   481
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
   482
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   483
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
   484
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
   485
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   486
  $ hg revert file2.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   487
  $ hg evolve --all
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   488
  move:[23] fix bug 67
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   489
  atop:[24] fix bug 53
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   490
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   491
Figure 10 illustrates the whole process.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   492
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   493
.. figure:: figures/figure-ug10.svg
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   494
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   495
   Figure 10: ``hg uncommit`` of a changeset with descendants results
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   496
   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
   497
   be dealt with.
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
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   500
Example 10: Uncommit files to an older changeset (keep changes)
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   501
===================================================================
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   502
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   503
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
   504
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
   505
bit more complicated. The setup is nearly identical::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   506
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   507
  $ echo 'fix a bug' >> file1.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   508
  $ echo 'useful but unrelated' >> file2.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   509
  $ 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
   510
  $ echo 'new feature' >> file1.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   511
  $ 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
   512
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   513
As before, we update back to the flawed changeset (this time,
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   514
revision 26) and ``uncommit``, leaving uncommitted changes to
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   515
``file2.c`` in the working dir::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   516
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   517
  $ hg update -q 26
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   518
  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
   519
  $ hg uncommit -q file2.c                        # obsoletes rev 26, creates rev 28
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   520
  1 new unstable changesets
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   521
  $ hg status
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   522
  M file2.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   523
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   524
This time, let's save that useful change before evolving::
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
  $ hg commit -m 'useful tweak'                   # rev 29
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   527
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   528
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
   529
and created revision 28, the successor of 26. Then we committed
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   530
revision 29, a child of 28. We still have to deal with the unstable
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   531
revision 27.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   532
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   533
.. figure:: figures/figure-ug11.svg
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   534
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   535
   Figure 11: Uncommitting a file and then committing that change
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   536
   separately will soon result in a two-headed repository.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   537
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   538
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
   539
unstable changesets, we want to evolve it::
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
  $ hg evolve --all
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   542
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   543
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
   544
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
   545
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
   546
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
   547
Unfortunately, that leaves us with a two-headed repository:
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   548
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   549
.. figure:: figures/figure-ug12.svg
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
   Figure 12: ``evolve`` takes care of unstable changesets; it does
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   552
   not solve all the world's problems.
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
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
   555
or rebase. It's up to you.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   556
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   557
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   558
Example 11: Recover an obsolete changeset
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   559
=========================================
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   560
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   561
TODO