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