docs/user-guide.rst
author Matt Harbison <matt_harbison@yahoo.com>
Sat, 10 Nov 2018 23:54:46 -0500
changeset 4254 8e891b4a54e8
parent 2931 83d2c9637e89
child 4615 8406d9b06130
permissions -rw-r--r--
compat: drop Mercurial 4.3 support for exthelper The last release email noted plans to drop 4.3 and 4.4 support in the next feature release. I'd like to move this code into core, and dropping this should allow the class to be copied in unmodified.
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
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   242
   revision 1 is preserved as an obsolete changeset. (The "temporary
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   243
   amend commit", marked with T, is an implementation detail stemming
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   244
   from limitations in Mercurial's current merge machinery. Future
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   245
   versions of Mercurial will not create them.)
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   246
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   247
In this case, the obsolete changesets are also *hidden*. That is the
2931
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
   248
usual end state for obsolete changesets. However, many scenarios result
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
   249
in obsolete changesets that are still visible, which indicates your
978
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   250
history modification work is not yet done. We'll see examples of that
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   251
later, when we cover advanced usage.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   252
1268
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
   253
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
   254
Understanding revision numbers and hidden changesets
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
   255
====================================================
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
   256
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
   257
As the name implies, hidden changesets are normally not visible. If
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
   258
you run ``hg log`` on the repository from Figure 2, Mercurial will
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
   259
show revisions 0 and 3, but not 1 and 2. That's something you don't
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
   260
see with plain vanilla Mercurial—normally, revision *N* is always
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
   261
followed by revision *N* + 1.
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
   262
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
   263
This is just the visible manifestation of hidden changesets. If
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
   264
revision 0 is followed by revision 3, that means there are two hidden
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
   265
changesets, 1 and 2, in between.
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
   266
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
   267
To see those hidden changesets, use the ``--hidden`` option::
978
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   268
1268
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
   269
  $ hg --hidden log --graph --template '{rev}:{node|short}  {desc|firstline}\n'
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
   270
  @  3:934359450037  implement feature Y
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
   271
  |
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
   272
  | x  2:6c5f78d5d467  temporary amend commit for fe0ecd3bd2a4
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
   273
  | |
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
   274
  | x  1:fe0ecd3bd2a4  implement feature Y
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
   275
  |/
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
   276
  o  0:08c4b6f4efc8  init
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
   277
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
   278
Note that changeset IDs are still the permanent, immutable identifier
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
   279
for changesets. Revision numbers are, as ever, a handy shorthand that
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
   280
work in your local repository, but cannot be used across repositories.
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
   281
They also have the useful property of showing when there are hidden
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
   282
changesets lurking under the covers, which is why this document uses
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
   283
revision numbers.
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
   284
978
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   285
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   286
Under the hood: Prune an unwanted changeset
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   287
===========================================
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   288
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   289
``prune`` (example 4 above) is the simplest history modification
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   290
command provided by ``evolve``. All it does is mark the specified
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   291
changeset(s) obsolete, with no successor/precursor relationships
2931
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
   292
involved. (If the working directory parent was one of the obsoleted
978
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   293
changesets, ``prune`` updates back to a suitable ancestor.)
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   294
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   295
.. figure:: figures/figure-ug03.svg
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   296
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   297
   Figure 3: pruning a changeset marks it obsolete with no successors.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   298
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   299
Under the hood: Uncommit changes to certain files
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   300
=================================================
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   301
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   302
In one sense, ``uncommit`` is a simplified version of ``amend``. Like
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   303
``amend``, it obsoletes one changeset and leaves it with a single
2931
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
   304
successor. In another sense, ``uncommit`` is the inverse of ``amend``:
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
   305
``amend`` takes any uncommitted changes in the working dir and “adds”
978
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   306
them to the working directory's parent changeset. (In reality, of
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   307
course, it creates a successor changeset, marking the original
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   308
obsolete.) In contrast, ``uncommit`` takes some changes in the working
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   309
directory's parent and moves them to the working dir, creating a new
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   310
successor changeset in the process. Figure 4 illustrates.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   311
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   312
.. figure:: figures/figure-ug04.svg
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   313
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   314
   Figure 4: uncommit moves some of the changes from the working
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   315
   directory parent into the working dir, preserving the remaining
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   316
   changes as a new successor changeset. (N.B. revision 4 is not shown
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   317
   here because it was marked obsolete in the previous example.)
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   318
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   319
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   320
Under the hood: Fold multiple changesets together into one
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   321
==========================================================
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   322
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   323
The last basic example is folding multiple changesets into one, which
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   324
marks multiple changesets obsolete, replacing them all with a single
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   325
successor.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   326
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   327
.. figure:: figures/figure-ug05.svg
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   328
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   329
   Figure 5: fold combines multiple changesets into a single
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   330
   successor, marking the original (folded) changesets obsolete.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   331
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   332
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   333
Obsolete is not hidden
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   334
======================
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   335
1269
250835154f8f docs: explain that obsolete is not hidden
Greg Ward <greg@gerg.ca>
parents: 1268
diff changeset
   336
So far, every obsolete changeset we have seen is also hidden. However,
250835154f8f docs: explain that obsolete is not hidden
Greg Ward <greg@gerg.ca>
parents: 1268
diff changeset
   337
these are *not* the same thing—that's why they have different names.
250835154f8f docs: explain that obsolete is not hidden
Greg Ward <greg@gerg.ca>
parents: 1268
diff changeset
   338
It's entirely possible to have obsolete changesets that are not
250835154f8f docs: explain that obsolete is not hidden
Greg Ward <greg@gerg.ca>
parents: 1268
diff changeset
   339
hidden. We'll see examples of that soon, when we create *unstable*
250835154f8f docs: explain that obsolete is not hidden
Greg Ward <greg@gerg.ca>
parents: 1268
diff changeset
   340
changesets.
250835154f8f docs: explain that obsolete is not hidden
Greg Ward <greg@gerg.ca>
parents: 1268
diff changeset
   341
250835154f8f docs: explain that obsolete is not hidden
Greg Ward <greg@gerg.ca>
parents: 1268
diff changeset
   342
Note that all hidden changesets are obsolete: hidden is a subset of
2931
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
   343
obsolete. This is explained in more depth in the `concepts`_ section.
978
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   344
2931
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
   345
.. _`concepts`: concepts.html
978
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   346
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   347
Life with ``evolve`` (advanced usage)
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   348
-------------------------------------
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   349
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   350
Now that you've got a solid understanding of how ``evolve`` works in
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   351
concert with changeset obsolescence, let's explore some more advanced
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   352
scenarios. All of these scenarios will involve *unstable* changesets,
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   353
which is an unavoidable consequence of obsolescence. What really sets
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   354
``evolve`` apart from other history modification mechanisms is the
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   355
fact that it recognizes troubles like unstable changesets and provides
2931
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
   356
a consistent way for you to get back to a stable repository.
978
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   357
2931
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
   358
(Incidentally, there are two other types of troubles that changesets
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
   359
can get into with ``evolve``: they may be *divergent* or
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
   360
*bumped*. Both of those states are more likely to occur when
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
   361
`sharing mutable history`_, so we won't cover them in this user guide.)
978
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   362
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   363
.. _`sharing mutable history`: sharing.html
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   364
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   365
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   366
Example 7: Amend an older changeset
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   367
===================================
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   368
2931
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
   369
Sometimes you don't notice a mistake until after you have committed
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
   370
new changesets on top of the changeset with the mistake. ::
978
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   371
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   372
  $ hg commit -m 'fix bug 17'         # rev 11 (mistake here)
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   373
  $ hg commit -m 'cleanup'            # rev 12
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   374
  $ hg commit -m 'feature 23'         # rev 13
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   375
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   376
Traditionally, your only option is to commit an "oops" changeset that
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   377
fixes your mistake. That works, of course, but it makes you look bad:
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   378
you made a mistake, and the record of that mistake is recorded in
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   379
history for all eternity. (If the mistake was in the commit message,
1267
8cc6e90354a9 docs: tweak wording, punctuation for better readability
Greg Ward <greg@gerg.ca>
parents: 978
diff changeset
   380
too bad: you cannot fix it.)
978
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   381
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   382
More subtly, there now exist changesets that are *worse* than what
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   383
came before—the code no longer builds, the tests don't pass, or
1267
8cc6e90354a9 docs: tweak wording, punctuation for better readability
Greg Ward <greg@gerg.ca>
parents: 978
diff changeset
   384
similar. Anyone reviewing these patches will waste time on the error
8cc6e90354a9 docs: tweak wording, punctuation for better readability
Greg Ward <greg@gerg.ca>
parents: 978
diff changeset
   385
in the earlier patch, and then the correction later on.
978
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   386
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   387
You can avoid all this by amending the bad changeset and *evolving*
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   388
subsequent history. Here's how it works, assuming you have just
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   389
committed revision 13 and noticed the mistake in revision 11::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   390
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   391
  $ hg update 11
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   392
  [...fix mistake...]
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   393
  $ hg amend
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   394
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   395
At this point, revision 11 is *obsolete* and revisions 12 and 13—the
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   396
descendants of 11—are in a funny state: they are *unstable*.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   397
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   398
.. figure:: figures/figure-ug06.svg
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   399
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   400
   Figure 6: amending a changeset with descendants means the amended
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   401
   changeset is obsolete but remains visible; its non-obsolete
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   402
   descendants are *unstable*. The temporary amend commit, revision
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   403
   14, is hidden because it has no non-obsolete descendants.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   404
2931
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
   405
All non-obsolete descendants of an obsolete changeset are considered
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
   406
unstable. An interesting consequence of this is that revision 11 is
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
   407
still visible, even though it is obsolete. Obsolete changesets with
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
   408
non-obsolete descendants are not hidden.
978
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   409
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   410
The fix is to *evolve* history::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   411
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   412
  $ hg evolve --all
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   413
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   414
This is a separate step, not automatically part of ``hg amend``,
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   415
because there might be conflicts. If your amended changeset modifies a
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   416
file that one of its descendants also modified, Mercurial has to fire
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   417
up your merge tool to resolve the conflict. More importantly, you have
2931
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
   418
to switch from "writing code" to "resolving conflicts". That can be an
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
   419
expensive context switch, so Mercurial lets you decide when to do it.
978
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   420
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   421
The end state, after ``evolve`` finishes, is that the original
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   422
revisions (11-13) are obsolete and hidden. Their successor revisions
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   423
(15-17) replace them.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   424
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   425
.. figure:: figures/figure-ug07.svg
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   426
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   427
   Figure 7: evolve your repository (``hg evolve --all``) to take care
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   428
   of instability. Unstable changesets become obsolete, and are
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   429
   replaced by successors just like the amended changeset was.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   430
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   431
Example 8: Prune an older changeset
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   432
===================================
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   433
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   434
Let's say you've just committed the following changesets::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   435
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   436
  $ hg commit -m 'useful work'       # rev 18
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   437
  $ hg commit -m 'debug hack'        # rev 19
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   438
  $ hg commit -m 'more work'         # rev 20
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   439
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   440
You want to drop revision 19, but keep 18 and 20. No problem::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   441
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   442
  $ hg prune 19
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   443
  1 changesets pruned
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   444
  1 new unstable changesets
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   445
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   446
As above, this leaves your repository in a funny intermediate state:
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   447
revision 20 is the non-obsolete descendant of obsolete revision 19.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   448
That is, revision 20 is unstable.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   449
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   450
.. figure:: figures/figure-ug08.svg
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   451
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   452
   Figure 8: ``hg prune`` marks a changeset obsolete without creating
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   453
   a successor. Just like with ``hg amend``, non-obsolete descendants
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   454
   of the pruned changeset are now unstable.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   455
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   456
As before, the solution to unstable changesets is to evolve your
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   457
repository::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   458
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   459
  $ hg evolve --all
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   460
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   461
This rebases revision 20 on top of 18 as the new revision 21, leaving
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   462
19 and 20 obsolete and hidden:
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   463
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   464
.. figure:: figures/figure-ug09.svg
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   465
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   466
   Figure 9: once again, ``hg evolve --all`` takes care of instability.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   467
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   468
Example 9: Uncommit files from an older changeset (discard changes)
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   469
=======================================================================
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   470
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   471
As in example 5, let's say you accidentally commit some unrelated
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   472
changes together. Unlike example 5, you don't notice your mistake
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   473
immediately, but commit a new changeset on top of the bad one. ::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   474
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   475
  $ echo 'this fixes bug 53' >> file1.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   476
  $ echo 'debug hack' >> file2.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   477
  $ hg commit -m 'fix bug 53'                     # rev 22 (oops)
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   478
  $ echo 'and this handles bug 67' >> file1.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   479
  $ hg commit -m 'fix bug 67'                     # rev 23 (fine)
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   480
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   481
As with ``amend``, you need to travel back in time and repair revision
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   482
22, leaving your changes to ``file2.c`` back in the working
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   483
directory::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   484
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   485
  $ hg update 22
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   486
  1 files updated, 0 files merged, 0 files removed, 0 files unresolved
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   487
  $ hg uncommit file2.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   488
  1 new unstable changesets
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   489
  $ hg status
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   490
  M file2.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   491
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   492
Now your repository has unstable changesets, so you need to evolve it.
2931
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
   493
However, ``hg evolve`` requires a clean working directory to resolve merge
978
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   494
conflicts, so you need to decide what to do with ``file2.c``.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   495
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   496
In this case, the change to ``file2.c`` was a temporary debugging
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   497
hack, so we can discard it and immediately evolve the instability away::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   498
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   499
  $ hg revert file2.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   500
  $ hg evolve --all
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   501
  move:[23] fix bug 67
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   502
  atop:[24] fix bug 53
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   503
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   504
Figure 10 illustrates the whole process.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   505
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   506
.. figure:: figures/figure-ug10.svg
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   507
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   508
   Figure 10: ``hg uncommit`` of a changeset with descendants results
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   509
   in instability *and* a dirty working directory, both of which must
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   510
   be dealt with.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   511
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   512
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   513
Example 10: Uncommit files to an older changeset (keep changes)
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   514
===================================================================
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   515
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   516
This is very similar to example 9. The difference that this time, our
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   517
change to ``file2.c`` is valuable enough to commit, making things a
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   518
bit more complicated. The setup is nearly identical::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   519
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   520
  $ echo 'fix a bug' >> file1.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   521
  $ echo 'useful but unrelated' >> file2.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   522
  $ hg commit -u dan -d '11 0' -m 'fix a bug'     # rev 26 (oops)
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   523
  $ echo 'new feature' >> file1.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   524
  $ hg commit -u dan -d '12 0' -m 'new feature'   # rev 27 (fine)
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   525
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   526
As before, we update back to the flawed changeset (this time,
2931
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
   527
revision 26) and use ``uncommit``, leaving uncommitted changes to
978
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   528
``file2.c`` in the working dir::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   529
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   530
  $ hg update -q 26
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   531
  1 files updated, 0 files merged, 0 files removed, 0 files unresolved
2931
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
   532
  $ hg uncommit -q file2.c  # obsoletes rev 26, creates rev 28
978
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   533
  1 new unstable changesets
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   534
  $ hg status
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   535
  M file2.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   536
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   537
This time, let's save that useful change before evolving::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   538
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   539
  $ hg commit -m 'useful tweak'                   # rev 29
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   540
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   541
Figure 11 shows the story so far: ``uncommit`` obsoleted revision 26
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   542
and created revision 28, the successor of 26. Then we committed
2931
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
   543
revision 29, a child of 28. We still have to deal with the revision 27,
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
   544
which is an unstable changeset.
978
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   545
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   546
.. figure:: figures/figure-ug11.svg
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   547
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   548
   Figure 11: Uncommitting a file and then committing that change
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   549
   separately will soon result in a two-headed repository.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   550
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   551
This is where things get tricky. As usual when a repository has
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   552
unstable changesets, we want to evolve it::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   553
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   554
  $ hg evolve --all
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   555
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   556
The problem is that ``hg evolve`` rebases revision 27 onto revision
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   557
28, creating 30 (the successor of 27). This is entirely logical: 27
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   558
was the child of 26, and 26's successor is 28. So of course 27's
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   559
successor (30) should be the child of 26's successor (28).
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   560
Unfortunately, that leaves us with a two-headed repository:
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   561
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   562
.. figure:: figures/figure-ug12.svg
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   563
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   564
   Figure 12: ``evolve`` takes care of unstable changesets; it does
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   565
   not solve all the world's problems.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   566
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   567
As usual when faced with a two-headed repository, you can either merge
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   568
or rebase. It's up to you.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   569
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   570
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   571
Example 11: Recover an obsolete changeset
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   572
=========================================
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   573
1270
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
   574
Sometimes you might obsolete a changeset, and then change your mind. You'll
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
   575
probably start looking for an “unobsolete” command to restore a changeset
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
   576
to normal state. For complicated implementation reasons, that command
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
   577
doesn't exist. (If you have already pushed an obsolescence marker to
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
   578
another repo, then Mercurial would need a way to revoke that remote
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
   579
obsolesence marker. That's a hard problem.)
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
   580
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
   581
Instead, ``evolve`` provides a ``touch`` command to resurrect an
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
   582
obsolete changeset. An unexpected quirk: you almost certainly need to
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
   583
use ``--hidden``, since obsolete changesets tend to be hidden, and you
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
   584
can't reference a hidden changeset otherwise. Typical usage thus looks
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
   585
like ::
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
   586
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
   587
  $ hg --hidden touch REV
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
   588
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
   589
This creates a new, normal changeset which is the same as ``REV``—except
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
   590
with a different changeset ID. The new changeset will have the same parent
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
   591
as ``REV``, and will be a successor of ``REV``.
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
   592
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
   593
The current implementation of ``hg touch`` is not ideal, and is likely to
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
   594
change in the future. Consider the history in Figure 12, where revision 27
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
   595
is obsolete and the child of 26, also obsolete. If we ``hg touch 27``, that
2931
83d2c9637e89 user-guide: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 1270
diff changeset
   596
creates a new revision which is a non-obsolete child of 26—i.e., it is an
1270
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
   597
unstable. It's also *divergent*, another type of trouble that we'll learn
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
   598
about in the `next section`_.
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
   599
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
   600
.. _`next section`: sharing.html