docs/user-guide.rst
author Pierre-Yves David <pierre-yves.david@octobus.net>
Fri, 14 Jul 2017 00:58:14 +0200
changeset 2734 39c3b2b5deb0
parent 1270 0683e3030316
child 2931 83d2c9637e89
permissions -rw-r--r--
prev: rename 'p' to 'target' This makes the code clearer.
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
978
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
     1
.. Copyright © 2014 Greg Ward <greg@gerg.ca>
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
     2
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
     3
------------------
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
     4
Evolve: User Guide
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
     5
------------------
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
     6
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
     7
.. contents::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
     8
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
     9
Life without ``evolve``
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    10
-----------------------
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    11
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    12
Before we dive into learning about ``evolve``, let's look into some
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    13
features of core Mercurial that interact with ``evolve``. ``commit``
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    14
affects ``evolve``, and ``evolve`` modifies how ``commit --amend``
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    15
works.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    16
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    17
Example 1: Commit a new changeset
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    18
=================================
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    19
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    20
To create a new changeset, simply run ``hg commit`` as usual.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    21
``evolve`` does not change the behaviour of ``commit`` at all.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    22
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    23
However, it's important to understand that new changesets are in the
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    24
*draft* phase by default: they are mutable. This means that they can
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    25
be modified by Mercurial's existing history-editing commands
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    26
(``rebase``, ``histedit``, etc.), and also by the ``evolve``
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    27
extension. Specifically, ``evolve`` adds a number of commands that can
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    28
be used to modify history: ``amend``, ``uncommit``, ``prune``,
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    29
``fold``, and ``evolve``. Generally speaking, changesets remain in
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    30
*draft* phase until they are pushed to another repository, at which
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    31
point they enter *public* phase. ::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    32
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    33
  $ hg commit -m 'implement feature X'
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    34
  $ hg phase -r .
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    35
  1: draft
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    36
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    37
(Strictly speaking, changesets only become public when they are pushed
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    38
to a *publishing* repository. But all repositories are publishing by
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    39
default; you have to explicitly configure repositories to be
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    40
*non-publishing*. Non-publishing repositories are an advanced topic
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    41
which we'll see when we get to `sharing mutable history`_.)
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    42
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    43
.. _`sharing mutable history`: sharing.html
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    44
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    45
Example 2: Amend a changeset (traditional)
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    46
==========================================
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    47
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    48
Imagine you've just committed a new changeset, and then you discover a
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    49
mistake. Maybe you forgot to run the tests and a failure slipped in.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    50
You want to modify history so that you push one perfect changeset,
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    51
rather than one flawed changeset followed by an "oops" commit. (Or
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    52
perhaps you made a typo in the commit message—this is really feature
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    53
*Y*, not feature X. You can't fix that with a followup commit.)
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    54
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    55
This is actually trivial with plain vanilla Mercurial since 2.2: fix
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    56
your mistake and run ::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    57
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    58
  $ hg commit --amend -m 'implement feature Y'
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    59
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    60
to create a new, amended changeset. The drawback of doing this with
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    61
vanilla Mercurial is that your original, flawed, changeset is removed
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    62
from the repository. This is *unsafe* history editing. It's probably
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    63
not too serious if all you did was fix a syntax error, but still.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    64
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    65
.. figure:: figures/figure-ug01.svg
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    66
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    67
   Figure 1: unsafe history modification with core Mercurial (not
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    68
   using ``evolve``): the original revision 1 is destroyed.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    69
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    70
(Incidentally, Mercurial's traditional history modification mechanism
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    71
isn't *really* unsafe: any changeset(s) removed from the repository
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    72
are kept in a backup directory, so you can manually restore them later
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    73
if you change your mind. But it's awkward and inconvenient compared to
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    74
the features provided by ``evolve`` and changeset obsolescence.)
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    75
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    76
Life with ``evolve`` (basic usage)
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    77
----------------------------------
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    78
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    79
Once you enable the ``evolve`` extension, a number of features are
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    80
available to you. First, we're going to explore several examples of
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    81
painless, trouble-free history modification.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    82
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    83
Example 3: Amend a changeset (with ``evolve``)
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    84
==============================================
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    85
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    86
Outwardly, amending a changeset with ``evolve`` can look exactly the
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    87
same as it does with core Mercurial (example 2)::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    88
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    89
  $ hg commit --amend -m 'implement feature Y'
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    90
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    91
Alternately, you can use the new ``amend`` command added by
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    92
``evolve``::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    93
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    94
  $ hg amend -m 'implement feature Y'
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    95
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    96
(``hg amend`` is nearly synonymous with ``hg commit --amend``. The
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    97
difference is that ``hg amend`` reuses the existing commit message by
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    98
default, whereas ``hg commit --amend`` runs your editor if you don't
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    99
pass ``-m`` or ``-l``.)
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   100
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   101
Under the hood, though, things are quite different. Mercurial has
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   102
simply marked the old changeset *obsolete*, replacing it with a new
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   103
one. We'll explore what this means in detail later, after working
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   104
through a few more examples.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   105
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   106
Example 4: Prune an unwanted changeset
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   107
======================================
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   108
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   109
Sometimes you make a change, and then decide it was such a bad idea
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   110
that you don't want anyone to know about it. Or maybe it was a
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   111
debugging hack that you needed to keep around for a while, but do not
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   112
intend to ever push publicly. ::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   113
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   114
  $ echo 'debug hack' >> file1.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   115
  $ hg commit -m 'debug hack'
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   116
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   117
In either case, ``hg prune`` is the answer. ``prune`` simply marks
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   118
changesets obsolete without creating any new changesets to replace
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   119
them::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   120
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   121
  $ hg prune .
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   122
  1 changesets pruned
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   123
  1 files updated, 0 files merged, 0 files removed, 0 files unresolved
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   124
  working directory now at 934359450037
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   125
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   126
Outwardly, it appears that your “debug hack” commit never happened;
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   127
we're right back where we started::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   128
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   129
  $ hg parents --template '{rev}:{node|short}  {desc|firstline}\n'
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   130
  3:934359450037  implement feature Y
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   131
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   132
In reality, though, the “debug hack” is still there, obsolete and hidden.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   133
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   134
Example 5: Uncommit changes to certain files
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   135
============================================
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   136
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   137
Occasionally you commit more than you intended: perhaps you made
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   138
unrelated changes to different files, and thus intend to commit
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   139
different files separately. ::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   140
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   141
  $ echo 'relevant' >> file1.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   142
  $ echo 'irrelevant' >> file2.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   143
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   144
If you forget to specify filenames on the ``commit`` command line,
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   145
Mercurial commits all those changes together::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   146
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   147
  $ hg commit -m 'fix bug 234'          # oops: too many files
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   148
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   149
Luckily, this mistake is easy to fix with ``uncommit``::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   150
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   151
  $ hg uncommit file2.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   152
  $ hg status
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   153
  M file2.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   154
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   155
Let's verify that the replacement changeset looks right (i.e.,
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   156
modifies only ``file1.c``)::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   157
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   158
  $ hg parents --template '{rev}:{node|short}  {desc|firstline}\n{files}\n'
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   159
  6:c8defeecf7a4  fix bug 234
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   160
  file1.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   161
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   162
As before, the original flawed changeset is still there, but obsolete
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   163
and hidden. It won't be exchanged with other repositories by ``push``,
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   164
``pull``, or ``clone``.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   165
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   166
Example 6: Fold multiple changesets together into one
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   167
=====================================================
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   168
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   169
If you're making extensive changes to fragile source code, you might
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   170
commit more frequently than normal so that you can fallback on a
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   171
known good state if one step goes badly. ::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   172
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   173
  $ echo step1 >> file1.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   174
  $ hg commit -m 'step 1'               # revision 7
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   175
  $ echo step2 >> file1.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   176
  $ hg commit -m 'step 2'               # revision 8
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   177
  $ echo step3 >> file2.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   178
  $ hg commit -m 'step 3'               # revision 9
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   179
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   180
At the end of such a sequence, you often end up with a series of small
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   181
changesets that are tedious to review individually. It might make more
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   182
sense to combine them into a single changeset using the ``fold``
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   183
command.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   184
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   185
To make sure we pass the right revisions to ``fold``, let's review the
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   186
changesets we just created, from revision 7::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   187
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   188
  $ hg log --template '{rev}:{node|short}  {desc|firstline}\n' -r 7::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   189
  7:05e61aab8294  step 1
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   190
  8:be6d5bc8e4cc  step 2
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   191
  9:35f432d9f7c1  step 3
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   192
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   193
and fold them::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   194
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   195
  $ hg fold -m 'fix bug 64' -r 7::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   196
  3 changesets folded
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   197
  1 files updated, 0 files merged, 0 files removed, 0 files unresolved
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   198
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   199
This time, Mercurial marks three changesets obsolete, replacing them
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   200
all with a single *successor*.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   201
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   202
(You might be familiar with this operation under other names, like
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   203
*squash* or *collapse*.)
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   204
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   205
Changeset obsolescence under the hood
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   206
-------------------------------------
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   207
1267
8cc6e90354a9 docs: tweak wording, punctuation for better readability
Greg Ward <greg@gerg.ca>
parents: 978
diff changeset
   208
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
   209
conflicts or other trouble. Before we start exploring advanced usage
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   210
that can run into trouble, let's step back and see what happens when
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   211
Mercurial marks changesets obsolete. That will make it much easier to
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   212
understand the more advanced use cases we'll see later.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   213
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   214
When you have the ``evolve`` extension enabled, all history
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   215
modification uses the same underlying mechanism: the original
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   216
changesets are marked *obsolete* and replaced by zero or more
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   217
*successors*. The obsolete changesets are the *precursors* of their
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   218
successors. This applies equally to built-in commands (``commit
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   219
--amend``), commands added by ``evolve`` (``amend``, ``prune``,
1267
8cc6e90354a9 docs: tweak wording, punctuation for better readability
Greg Ward <greg@gerg.ca>
parents: 978
diff changeset
   220
``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
   221
(``rebase``, ``histedit``).
978
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   222
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   223
Another way of looking at it is that obsolescence is second-order
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   224
version control, i.e. the history of your history. We'll cover this in
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   225
more detail (and mathematical precision) in the `concepts`_ guide.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   226
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   227
.. _`concepts`: concepts.html
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   228
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   229
Under the hood: Amend a changeset
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   230
=================================
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   231
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   232
Consider Example 2, amending a changeset with ``evolve``. We saw above
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   233
that you can do this using the exact same command-line syntax as core
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   234
Mercurial, namely ``hg commit --amend``. But the implementation is
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   235
quite different, and Figure 2 shows how.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   236
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   237
.. figure:: figures/figure-ug02.svg
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   238
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   239
   Figure 2: safe history modification using ``evolve``: the original
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   240
   revision 1 is preserved as an obsolete changeset. (The "temporary
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   241
   amend commit", marked with T, is an implementation detail stemming
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   242
   from limitations in Mercurial's current merge machinery. Future
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   243
   versions of Mercurial will not create them.)
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   244
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   245
In this case, the obsolete changesets are also *hidden*. That is the
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   246
usual end state for obsolete changesets. But many scenarios result in
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   247
obsolete changesets that are still visible, which indicates your
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   248
history modification work is not yet done. We'll see examples of that
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   249
later, when we cover advanced usage.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   250
1268
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
   251
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
   252
Understanding revision numbers and hidden changesets
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
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
   255
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
   256
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
   257
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
   258
see with plain vanilla Mercurial—normally, revision *N* is always
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
   259
followed by revision *N* + 1.
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
   260
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
   261
This is just the visible manifestation of hidden changesets. If
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
   262
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
   263
changesets, 1 and 2, in between.
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
   264
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
   265
To see those hidden changesets, use the ``--hidden`` option::
978
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   266
1268
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
   267
  $ 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
   268
  @  3:934359450037  implement feature Y
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
   269
  |
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
   270
  | x  2:6c5f78d5d467  temporary amend commit for fe0ecd3bd2a4
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  1:fe0ecd3bd2a4  implement feature Y
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
  o  0:08c4b6f4efc8  init
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
Note that changeset IDs are still the permanent, immutable identifier
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
   277
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
   278
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
   279
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
   280
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
   281
revision numbers.
ba3ff8c00304 docs: explain --hidden option
Greg Ward <greg@gerg.ca>
parents: 1267
diff changeset
   282
978
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
Under the hood: Prune an unwanted changeset
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
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   287
``prune`` (example 4 above) is the simplest history modification
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   288
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
   289
changeset(s) obsolete, with no successor/precursor relationships
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   290
involved. (If the working directory parent was one of the obsolete
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   291
changesets, ``prune`` updates back to a suitable ancestor.)
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   292
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   293
.. figure:: figures/figure-ug03.svg
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 3: pruning a changeset marks it obsolete with no successors.
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
Under the hood: Uncommit changes to certain files
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
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   300
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
   301
``amend``, it obsoletes one changeset and leaves it with a single
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   302
successor. Unlike ``amend``, there is no ugly "temporary amend commit"
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   303
cluttering up the repository.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   304
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   305
In another sense, ``uncommit`` is the inverse of ``amend``: ``amend``
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   306
takes any uncommitted changes in the working dir and “adds”
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   307
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
   308
course, it creates a successor changeset, marking the original
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   309
obsolete.) In contrast, ``uncommit`` takes some changes in the working
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   310
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
   311
successor changeset in the process. Figure 4 illustrates.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   312
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   313
.. figure:: figures/figure-ug04.svg
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
   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
   316
   directory parent into the working dir, preserving the remaining
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   317
   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
   318
   here because it was marked obsolete in the previous example.)
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
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   321
Under the hood: Fold multiple changesets together into one
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
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   324
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
   325
marks multiple changesets obsolete, replacing them all with a single
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   326
successor.
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
.. figure:: figures/figure-ug05.svg
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
   Figure 5: fold combines multiple changesets into a single
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   331
   successor, marking the original (folded) changesets obsolete.
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
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   334
Obsolete is not hidden
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   335
======================
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   336
1269
250835154f8f docs: explain that obsolete is not hidden
Greg Ward <greg@gerg.ca>
parents: 1268
diff changeset
   337
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
   338
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
   339
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
   340
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
   341
changesets.
250835154f8f docs: explain that obsolete is not hidden
Greg Ward <greg@gerg.ca>
parents: 1268
diff changeset
   342
250835154f8f docs: explain that obsolete is not hidden
Greg Ward <greg@gerg.ca>
parents: 1268
diff changeset
   343
Note that all hidden changesets are obsolete: hidden is a subset of
250835154f8f docs: explain that obsolete is not hidden
Greg Ward <greg@gerg.ca>
parents: 1268
diff changeset
   344
obsolete.
978
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   345
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
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   356
a consistent way for you to get out of trouble.
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
(Incidentally, there are two other types of trouble that changesets
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   359
can get into with ``evolve``: they may be *divergent* or *bumped*.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   360
Both of those states are more likely to occur when `sharing mutable
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   361
history`_, so we won't see them in this user guide.)
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   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
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   369
Sometimes you don't notice your mistakes until after you have
1267
8cc6e90354a9 docs: tweak wording, punctuation for better readability
Greg Ward <greg@gerg.ca>
parents: 978
diff changeset
   370
committed new changesets on top of them. ::
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
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   405
All non-obsolete descendants of an obsolete changeset are unstable. An
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   406
interesting consequence of this is that revision 11 is still visible,
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   407
even though it is obsolete. Obsolete changesets with non-obsolete
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   408
descendants are not hidden.
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
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   418
to switch contexts from "writing code" to "resolving conflicts". That
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   419
can be an expensive context switch, so Mercurial lets you decide when
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   420
to do it.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   421
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   422
The end state, after ``evolve`` finishes, is that the original
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   423
revisions (11-13) are obsolete and hidden. Their successor revisions
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   424
(15-17) replace them.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   425
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   426
.. figure:: figures/figure-ug07.svg
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
   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
   429
   of instability. Unstable changesets become obsolete, and are
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   430
   replaced by successors just like the amended changeset was.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   431
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   432
Example 8: Prune an older changeset
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
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   435
Let's say you've just committed the following changesets::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   436
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   437
  $ hg commit -m 'useful work'       # rev 18
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   438
  $ hg commit -m 'debug hack'        # rev 19
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   439
  $ hg commit -m 'more work'         # rev 20
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   440
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   441
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
   442
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   443
  $ hg prune 19
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   444
  1 changesets pruned
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   445
  1 new unstable changesets
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   446
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   447
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
   448
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
   449
That is, revision 20 is unstable.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   450
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   451
.. figure:: figures/figure-ug08.svg
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   452
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   453
   Figure 8: ``hg prune`` marks a changeset obsolete without creating
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   454
   a successor. Just like with ``hg amend``, non-obsolete descendants
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   455
   of the pruned changeset are now unstable.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   456
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   457
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
   458
repository::
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
  $ hg evolve --all
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
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
   463
19 and 20 obsolete and hidden:
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
.. figure:: figures/figure-ug09.svg
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   466
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   467
   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
   468
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   469
Example 9: Uncommit files from an older changeset (discard changes)
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
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   472
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
   473
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
   474
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
   475
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   476
  $ echo 'this fixes bug 53' >> file1.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   477
  $ echo 'debug hack' >> file2.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   478
  $ hg commit -m 'fix bug 53'                     # rev 22 (oops)
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   479
  $ echo 'and this handles bug 67' >> file1.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   480
  $ hg commit -m 'fix bug 67'                     # rev 23 (fine)
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   481
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   482
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
   483
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
   484
directory::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   485
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   486
  $ hg update 22
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   487
  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
   488
  $ hg uncommit file2.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   489
  1 new unstable changesets
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   490
  $ hg status
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   491
  M file2.c
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
Now your repository has unstable changesets, so you need to evolve it.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   494
But ``hg evolve`` requires a clean working directory to resolve merge
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   495
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
   496
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   497
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
   498
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
   499
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   500
  $ hg revert file2.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   501
  $ hg evolve --all
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   502
  move:[23] fix bug 67
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   503
  atop:[24] fix bug 53
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   504
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   505
Figure 10 illustrates the whole process.
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
.. figure:: figures/figure-ug10.svg
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
   Figure 10: ``hg uncommit`` of a changeset with descendants results
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   510
   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
   511
   be dealt with.
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
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   514
Example 10: Uncommit files to an older changeset (keep changes)
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
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   517
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
   518
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
   519
bit more complicated. The setup is nearly identical::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   520
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   521
  $ echo 'fix a bug' >> file1.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   522
  $ echo 'useful but unrelated' >> file2.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   523
  $ 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
   524
  $ echo 'new feature' >> file1.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   525
  $ 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
   526
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   527
As before, we update back to the flawed changeset (this time,
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   528
revision 26) and ``uncommit``, leaving uncommitted changes to
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   529
``file2.c`` in the working dir::
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
  $ hg update -q 26
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   532
  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
   533
  $ hg uncommit -q file2.c                        # obsoletes rev 26, creates rev 28
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   534
  1 new unstable changesets
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   535
  $ hg status
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   536
  M file2.c
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   537
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   538
This time, let's save that useful change before evolving::
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
  $ hg commit -m 'useful tweak'                   # rev 29
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 shows the story so far: ``uncommit`` obsoleted revision 26
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   543
and created revision 28, the successor of 26. Then we committed
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   544
revision 29, a child of 28. We still have to deal with the unstable
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   545
revision 27.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   546
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   547
.. figure:: figures/figure-ug11.svg
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   548
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   549
   Figure 11: Uncommitting a file and then committing that change
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   550
   separately will soon result in a two-headed repository.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   551
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   552
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
   553
unstable changesets, we want to evolve it::
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   554
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   555
  $ hg evolve --all
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   556
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   557
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
   558
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
   559
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
   560
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
   561
Unfortunately, that leaves us with a two-headed repository:
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   562
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   563
.. figure:: figures/figure-ug12.svg
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
   Figure 12: ``evolve`` takes care of unstable changesets; it does
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   566
   not solve all the world's problems.
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   567
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   568
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
   569
or rebase. It's up to you.
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
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   572
Example 11: Recover an obsolete changeset
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   573
=========================================
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   574
1270
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
   575
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
   576
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
   577
to normal state. For complicated implementation reasons, that command
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
   578
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
   579
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
   580
obsolesence marker. That's a hard problem.)
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
   581
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
   582
Instead, ``evolve`` provides a ``touch`` command to resurrect an
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
   583
obsolete changeset. An unexpected quirk: you almost certainly need to
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
   584
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
   585
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
   586
like ::
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
   587
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
   588
  $ hg --hidden touch REV
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
   589
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
   590
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
   591
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
   592
as ``REV``, and will be a successor of ``REV``.
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
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
   595
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
   596
is obsolete and the child of 26, also obsolete. If we ``hg touch 27``, that
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
   597
creates a new revision which is a non-obsolete child of 26—i.e., it is
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
   598
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
   599
about in the `next section`_.
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
   600
0683e3030316 docs: cover 'touch' command
Greg Ward <greg@gerg.ca>
parents: 1269
diff changeset
   601
.. _`next section`: sharing.html