author | Pierre-Yves David <pierre-yves.david@octobus.net> |
Mon, 29 May 2017 16:59:59 +0200 | |
changeset 2495 | 0db53f48db2d |
parent 1288 | c3ecf6871872 |
child 4618 | 803d32f4e498 |
permissions | -rw-r--r-- |
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 } |