docs/concepts.rst
author Boris Feld <boris.feld@octobus.net>
Sun, 04 Jun 2017 20:47:04 +0200
changeset 2577 5506b463bddc
parent 1288 c3ecf6871872
child 4618 803d32f4e498
permissions -rw-r--r--
effectflag: activate effect flag on test-stabilize-result.t test file Prepare activation of effect flag by default by activating it on test- stabilize-result.t test file first.
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 }