docs/concepts.rst
author Laurent Charignon <lcharignon@fb.com>
Wed, 20 May 2015 12:46:13 -0700
changeset 1364 f00d91365ab9
parent 1288 c3ecf6871872
child 4618 803d32f4e498
permissions -rw-r--r--
evolve: make uncommit respect allowunsable Before this patch, the uncommit command was performing the same way regardless of the value of experimental.evolution. With this patch if the configuration does not allow unstability, uncommit won't create instability.
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
980
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
     1
.. Copyright 2014 Greg Ward <greg@gerg.ca>
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
     2
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
     3
----------------
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
     4
Evolve: Concepts
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
     5
----------------
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
     6
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
     7
Getting the most out of software requires an accurate understanding of
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
     8
the concepts underlying it. For example, you cannot use Mercurial to
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
     9
its full potential without understanding the DAG (directed acyclic
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    10
graph) of changesets and the meaning of parent/child relationships
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    11
between nodes in that graph. Mercurial with changeset evolution adds
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    12
some additional concepts to the graph of changesets. Understanding
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    13
those concepts will make you an informed and empowered user of
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    14
``evolve``.
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    15
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    16
.. note:: This document contains math! If you have a pathological fear
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    17
          of set theory and the associated notation, you might be
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    18
          better off just reading the `user guide`_. But if you
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    19
          appreciate the theoretical rigour underlying core Mercurial,
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    20
          you will be happy to know that it continues right into
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    21
          changeset evolution.
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    22
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    23
.. note:: This document is incomplete! (The formatting of the math
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    24
          isn't quite right yet, and the diagrams are missing for
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    25
          malformatted.)
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    26
1288
c3ecf6871872 docs: format concepts guide better, with literal blocks
Greg Ward <greg@gerg.ca>
parents: 980
diff changeset
    27
This document follows standard set theory notation::
980
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    28
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    29
  x ∈ A: x is a member of A
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    30
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    31
  A ∪ B: union of A and B: { x | x ∈ A or x ∈ B }
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    32
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    33
  A ∖ B: set difference: { x | x ∈ A and x ∉ B }
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    34
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    35
  A ⊇ B: superset: if x ∈ B, then x ∈ A
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    36
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    37
.. _`user guide`: user-guide.html
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    38
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    39
Phases
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    40
------
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    41
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    42
First, every changeset in a Mercurial repository (since 2.3) has a
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    43
*phase*. Phases are independent of ``evolve`` and they affect
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    44
Mercurial usage with or without changeset evolution. However, they
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    45
were implemented in order to support evolution, and are a critical
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    46
foundation of ``evolve``.
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    47
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    48
Phases are strictly ordered:
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    49
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    50
  secret > draft > public
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    51
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    52
Changesets generally only move from a higher phase to a lower phase.
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    53
Typically, changesets start life in *draft* phase, and move to
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    54
*public* phase when they are pushed to a public repository. (You can
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    55
set the default phase of new commits in Mercurial configuration.)
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    56
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    57
The purpose of phases is to prevent modifying published history.
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    58
``evolve`` will therefore only let you rewrite changesets in one of
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    59
the two *mutable* phases (secret or draft).
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    60
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    61
Run ``hg help phases`` for more information on phases.
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    62
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    63
Obsolete changesets
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    64
-------------------
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    65
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    66
*Obsolescence* is they key concept at the heart of changeset
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    67
evolution. Everything else in this document depends on understanding
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    68
obsolescence. So: what does it mean for a changeset to be obsolete?
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    69
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    70
In implementation terms, there is an *obsolescence marker* associated
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    71
with changesets: every changeset is either obsolete or not.
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    72
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    73
The simplest way that a changeset becomes obsolete is by *pruning* it.
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    74
The ``hg prune`` command simply marks the specified changesets
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    75
obsolete, as long as they are mutable.
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    76
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    77
More commonly, a changeset *A* becomes obsolete by *amending* it.
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    78
Amendment creates a new changeset *A'* that replaces *A*, which is now
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    79
obsolete. *A'* is the successor of *A*, and *A* the predecessor of *A'*:
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    80
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    81
  [diagram: A and A' with pred/succ edge]
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    82
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    83
The predecessor/successor relationship forms an additional
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    84
*obsolescence graph* overlaid on top of the traditional DAG formed by
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    85
changesets and their parent/child relationships. In fact, the
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    86
obsolescence graph is second-order version control. Where the
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    87
traditional parent/child DAG tracks changes to your source code, the
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    88
obsolescence graph tracks changes to your changesets. It tracks the
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    89
evolution of your changesets.
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    90
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    91
(If you prefer a calculus metaphor to set theory, it might help to
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    92
think of the traditional parent/child DAG as the first derivative of
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    93
your source code, and the obsolescence DAG as the second derivative.)
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    94
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    95
Troubled changesets (unstable, bumped, divergent)
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    96
-------------------------------------------------
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    97
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    98
Evolving history can introduce problems that need to be solved. For
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    99
example, if you prune a changeset *P* but not its descendants, those
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   100
descendants are now on thin ice. To push a changeset to another
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   101
repository *R*, all of its ancestors must be present in *R* or pushed
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   102
at the same time. But Mercurial does not push obsolete changesets like
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   103
*P*, so it cannot push the descendants of *P*. Any non-obsolete
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   104
changeset that is a descendant of an obsolete changeset is said to be
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   105
*unstable*.
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   106
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   107
  [diagram: obsolete cset with non-obsolete descendant]
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   108
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   109
Another sort of trouble occurs when two developers, Alice and Bob,
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   110
collaborate via a shared non-publishing repository. (This is how
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   111
developers can safely `share mutable history`_.) Say Alice and Bob
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   112
both start the day with changeset *C* in *draft* phase. If Alice
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   113
pushes *C* to their public repository, then it is now published and
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   114
therefore immutable. But Bob is working from a desert island and
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   115
cannot pull this change in *C*'s phase. For Bob, *C* is still in draft
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   116
phase and therefore mutable. So Bob amends *C*, which marks it
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   117
obsolete and replaces it with *C'*. When he is back online and pulls
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   118
from the public repository, Mercurial learns that *C* is public, which
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   119
means it cannot be obsolete. We say that *C'* is *bumped*, since it is
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   120
the successor of a public changeset.
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   121
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   122
.. _`share mutable history`: sharing.html
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   123
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   124
(Incidentally, the terminology here comes from airline overbooking: if
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   125
two people have bought tickets for the same seat on a plane and they
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   126
both show up at the airport, only one of them gets on the plane. The
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   127
passenger who is left behind in the airport terminal has been
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   128
"bumped".)
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   129
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   130
The third sort of trouble is when Alice and Bob both amend the same
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   131
changeset *C* to have different successors. When this happens, the
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   132
successors are both called *divergent* (unless one of them is in
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   133
public phase; only mutable changesets are divergent).
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   134
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   135
The collective term for unstable, bumped, and divergent changeset is
1288
c3ecf6871872 docs: format concepts guide better, with literal blocks
Greg Ward <greg@gerg.ca>
parents: 980
diff changeset
   136
*troubled*::
980
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   137
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   138
  troubled = unstable ∪ bumped ∪ divergent
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   139
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   140
It is possible for a changeset to be in any of the troubled categories
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   141
at the same time: it might be unstable and divergent, or bumped and
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   142
divergent, or whatever.
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   143
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   144
  [diagram: Venn diagram of troubled changesets, showing overlap]
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   145
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   146
The presence of troubled changesets indicates the need to run ``hg
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   147
evolve``.
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   148
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   149
Hidden (and visible) changesets
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   150
-------------------------------
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   151
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   152
Some obsolete changesets are *hidden*: deliberately suppressed by
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   153
Mercurial and usually not visible through the UI. (As of Mercurial
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   154
2.9, there are still some commands that inadvertently reveal hidden
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   155
changesets; these are bugs and will be fixed in due course.)
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   156
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   157
All hidden changesets are obsolete, and all obsolete changesets are
1288
c3ecf6871872 docs: format concepts guide better, with literal blocks
Greg Ward <greg@gerg.ca>
parents: 980
diff changeset
   158
part of your repository. Mathematically speaking::
980
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   159
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   160
  repo ⊇ obsolete ⊇ hidden
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   161
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   162
Or, putting it visually:
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   163
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   164
  [diagram: Venn diagram showing nested strict subsets]
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   165
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   166
However, the presence of obsolete but not hidden changesets should be
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   167
temporary. The desired end state for any history mutation operation is
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   168
that all obsolete changesets are hidden, i.e.:
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   169
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   170
  repo ⊇ obsolete, obsolete = hidden
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   171
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   172
Visually:
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   173
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   174
  [diagram: Venn diagram showing obsolete = hidden, subset of repo]
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   175
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   176
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   177
Why is this changeset visible?
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   178
------------------------------
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   179
1288
c3ecf6871872 docs: format concepts guide better, with literal blocks
Greg Ward <greg@gerg.ca>
parents: 980
diff changeset
   180
Any changeset which is not hidden is *visible*. That is, ::
980
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   181
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   182
  visible = repo ∖ hidden
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   183
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   184
(Recall that ∖ means set difference: *visible* is the set of
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   185
changesets that are in *repo* but not in *hidden*.)
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   186
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   187
After amending or pruning a changeset, you might expect it to be
1288
c3ecf6871872 docs: format concepts guide better, with literal blocks
Greg Ward <greg@gerg.ca>
parents: 980
diff changeset
   188
hidden. It doesn't always work out that way. The precise rules are::
980
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   189
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   190
  hideable = obsolete
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   191
  blockers = bookmarks ∪ parents(workingcopy) ∪ localtags
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   192
  hidden = hideable ∖ ancestors((repo ∖ hideable) ∪ blockers)
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   193
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   194
This will probably be clearer with a worked example. First, here's a
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   195
repository with some obsolete changesets, some troubled changesets,
1288
c3ecf6871872 docs: format concepts guide better, with literal blocks
Greg Ward <greg@gerg.ca>
parents: 980
diff changeset
   196
one bookmark, a working copy, and some hidden changesets::
980
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   197
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   198
        x-x
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   199
       /
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   200
  -o-o-o-o
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   201
     \
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   202
      x-x-o
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   203
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   204
Here's the computation required to determine which changesets are
1288
c3ecf6871872 docs: format concepts guide better, with literal blocks
Greg Ward <greg@gerg.ca>
parents: 980
diff changeset
   205
hidden::
980
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   206
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   207
  repo = { 0, 1, 2, 3, 4, 5, 6, 7, 8 }
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   208
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   209
  hideable = obsolete = { 2, 4, 5, 8 }
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   210
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   211
  blockers = { 6 } ∪ { 4 } ∪ {}
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   212
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   213
  blockers = { 4, 6 }
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   214
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   215
  hidden = hideable ∖ ancestors((repo ∖ { 2, 4, 5, 8 }) ∪ { 4, 6 })
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   216
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   217
  hidden = hideable ∖ ancestors({ 0, 1, 3, 6, 7 } ∪ { 4, 6 })
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   218
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   219
  hidden = hideable ∖ ancestors({ 0, 1, 3, 4, 6, 7 })
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   220
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   221
  hidden = { 2, 4, 5, 8 } ∖ { 0, 1, 2, 3, 4, 5, 6, 7 }
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   222
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   223
  hidden = { 8 }