docs/obs-terms.rst
changeset 4660 b62ed7c69561
parent 4621 8784dfc6537c
equal deleted inserted replaced
4659:4d2f8c99f23a 4660:b62ed7c69561
    10 
    10 
    11 The mutable concept is based on **obsolete markers**. Creating an obsolete
    11 The mutable concept is based on **obsolete markers**. Creating an obsolete
    12 marker registers a relation between an old obsoleted changeset and its newer
    12 marker registers a relation between an old obsoleted changeset and its newer
    13 version.
    13 version.
    14 
    14 
    15 Old changesets are called **precursors** while their new versions are called
    15 Old changesets are called **predecessors** while their new versions are called
    16 **successors**. A marker always registers a single *precursor* and:
    16 **successors**. A marker always registers a single *predecessor* and:
    17 
    17 
    18 - no *successor*: the *precursor* is just discarded.
    18 - no *successor*: the *predecessor* is just discarded.
    19 - one *successor*: the *precursor* has been rewritten
    19 - one *successor*: the *predecessor* has been rewritten
    20 - multiple *successors*: the *precursor* were splits in multiple
    20 - multiple *successors*: the *predecessor* were splits in multiple
    21   changesets.
    21   changesets.
    22 
    22 
    23 .. The *precursors* and *successors* terms can be used on changeset directly:
    23 .. The *predecessors* and *successors* terms can be used on changeset directly:
    24 
    24 
    25 .. :precursors: of a changeset `A` are changesets used as *precursors* by
    25 .. :predecessors: of a changeset `A` are changesets used as *predecessors* by
    26 ..              obsolete marker using changeset `A` as *successors*
    26 ..              obsolete marker using changeset `A` as *successors*
    27 
    27 
    28 .. :successors: of a changeset `B` are changesets used as *successors* by
    28 .. :successors: of a changeset `B` are changesets used as *successors* by
    29 ..              obsolete marker using changeset `B` as *precursors*
    29 ..              obsolete marker using changeset `B` as *predecessors*
    30 
    30 
    31 Chaining obsolete markers is allowed to rewrite a changeset that is already a
    31 Chaining obsolete markers is allowed to rewrite a changeset that is already a
    32 *successor*. This is a kind of *second order version control*.
    32 *successor*. This is a kind of *second order version control*.
    33 To clarify ambiguous situations one can use **direct precursors** or
    33 To clarify ambiguous situations one can use **direct predecessors** or
    34 **direct successors** to name changesets that are directly related.
    34 **direct successors** to name changesets that are directly related.
    35 
    35 
    36 The set of all *obsolete markers* forms a direct acyclic graph the same way
    36 The set of all *obsolete markers* forms a direct acyclic graph the same way
    37 standard *parents*/*children* relation does. In this graph we have:
    37 standard *parents*/*children* relation does. In this graph we have:
    38 
    38 
    39 :any precursors: are transitive precursors of a changeset: *direct precursors*
    39 :any predecessors: are transitive predecessors of a changeset: *direct predecessors*
    40                  and *precursors* of *precursors*.
    40                  and *predecessors* of *predecessors*.
    41 
    41 
    42 :any successors: are transitive successors of a changeset: *direct successors*
    42 :any successors: are transitive successors of a changeset: *direct successors*
    43                  and *successors*  of *successors*)
    43                  and *successors*  of *successors*)
    44 
    44 
    45 Obsolete markers may refer changesets that are not known locally.
    45 Obsolete markers may refer changesets that are not known locally.
    46 So, *direct precursors* of a changeset may be unknown locally.
    46 So, *direct predecessors* of a changeset may be unknown locally.
    47 This is why we usually focus on the **first known precursors**  of the rewritten
    47 This is why we usually focus on the **first known predecessors**  of the rewritten
    48 changeset. The same apply for *successors*.
    48 changeset. The same apply for *successors*.
    49 
    49 
    50 Changeset in *any successors* which are not **obsolete** are called
    50 Changeset in *any successors* which are not **obsolete** are called
    51 **newest successors**..
    51 **newest successors**..
    52 
    52 
    64 +---------------------+--------------------------+-----------------------------+
    64 +---------------------+--------------------------+-----------------------------+
    65 | **mutable**         | **obsolete**             | **extinct**                 |
    65 | **mutable**         | **obsolete**             | **extinct**                 |
    66 |                     |                          |                             |
    66 |                     |                          |                             |
    67 | Changeset in either | Obsolete changeset is    | *extinct* changeset is      |
    67 | Changeset in either | Obsolete changeset is    | *extinct* changeset is      |
    68 | *draft* or *secret* | *mutable* used as a      | *obsolete* which has only   |
    68 | *draft* or *secret* | *mutable* used as a      | *obsolete* which has only   |
    69 | phase.              | *precursor*.             | *obsolete* descendants.     |
    69 | phase.              | *predecessor*.           | *obsolete* descendants.     |
    70 |                     |                          |                             |
    70 |                     |                          |                             |
    71 |                     | A changeset is used as   | They can safely be:         |
    71 |                     | A changeset is used as   | They can safely be:         |
    72 |                     | a *precursor* when at    |                             |
    72 |                     | a *predecessor* when at  |                             |
    73 |                     | least one obsolete       | - hidden in the UI,         |
    73 |                     | least one obsolete       | - hidden in the UI,         |
    74 |                     | marker refers to it      | - silently excluded from    |
    74 |                     | marker refers to it      | - silently excluded from    |
    75 |                     | as precursors.           |   pull and push operations  |
    75 |                     | as predecessors.         |   pull and push operations  |
    76 |                     |                          | - mostly ignored            |
    76 |                     |                          | - mostly ignored            |
    77 |                     |                          | - garbage collected         |
    77 |                     |                          | - garbage collected         |
    78 |                     |                          |                             |
    78 |                     |                          |                             |
    79 |                     |                          +-----------------------------+
    79 |                     |                          +-----------------------------+
    80 |                     |                          |                             |
    80 |                     |                          |                             |
    90 |                     |                          | they will refuse to be      |
    90 |                     |                          | they will refuse to be      |
    91 |                     |                          | pushed without --force.     |
    91 |                     |                          | pushed without --force.     |
    92 |                     |                          |                             |
    92 |                     |                          |                             |
    93 |                     +--------------------------+-----------------------------+
    93 |                     +--------------------------+-----------------------------+
    94 |                     |                          |                             |
    94 |                     |                          |                             |
    95 |                     | **troubled**             | **unstable**                |
    95 |                     | **unstable**             | **orphan**                  |
    96 |                     |                          |                             |
    96 |                     |                          |                             |
    97 |                     | *troubled*    has        | *unstable* is a changeset   |
    97 |                     | *unstable*    has        | *orphan* is a changeset     |
    98 |                     | unresolved issue caused  | with obsolete ancestors.    |
    98 |                     | unresolved issue caused  | with obsolete ancestors.    |
    99 |                     | by *obsolete* relations. |                             |
    99 |                     | by *obsolete* relations. |                             |
   100 |                     |                          |                             |
   100 |                     |                          |                             |
   101 |                     | Possible issues are      | It must be rebased on a     |
   101 |                     | Possible issues are      | It must be rebased on a     |
   102 |                     | listed in the next       | non *troubled*    base to   |
   102 |                     | listed in the next       | non *unstable*    base to   |
   103 |                     | column. It is possible   | solve the problem.          |
   103 |                     | column. It is possible   | solve the problem.          |
   104 |                     | for *troubled*           |                             |
   104 |                     | for *unstable*           |                             |
   105 |                     | changeset to combine     | (possible alternative name: |
   105 |                     | changeset to combine     | (possible alternative name: |
   106 |                     | multiple issue at once.  | precarious)                 |
   106 |                     | multiple issue at once.  | precarious)                 |
   107 |                     | (a.k.a. divergent   and  |                             |
   107 |                     | (a.k.a. content-divergent|                             |
   108 |                     | unstable)                +-----------------------------+
   108 |                     | and orphan)              +-----------------------------+
   109 |                     |                          |                             |
   109 |                     |                          |                             |
   110 |                     | (possible alternative    | **bumped**                  |
   110 |                     | (possible alternative    | **phase-divergent**         |
   111 |                     | names: unsettled,        |                             |
   111 |                     | names: unsettled,        |                             |
   112 |                     | troublesome              | *bumped* is a changeset     |
   112 |                     | troublesome              | *phase-divergent* is a      |
   113 |                     |                          | that tries to be successor  |
   113 |                     |                          | changeset that tries to be  |
   114 |                     |                          | of  public changesets.      |
   114 |                     |                          | successor of a public       |
       
   115 |                     |                          | changeset.                  |
   115 |                     |                          |                             |
   116 |                     |                          |                             |
   116 |                     |                          | Public changeset can't      |
   117 |                     |                          | Public changeset can't      |
   117 |                     |                          | be deleted and replace      |
   118 |                     |                          | be deleted and replace      |
   118 |                     |                          | *bumped*                    |
   119 |                     |                          | *phase-divergent*           |
   119 |                     |                          | need to be converted into   |
   120 |                     |                          | need to be converted into   |
   120 |                     |                          | an overlay to this public   |
   121 |                     |                          | an overlay to this public   |
   121 |                     |                          | changeset.                  |
   122 |                     |                          | changeset.                  |
   122 |                     |                          |                             |
   123 |                     |                          |                             |
   123 |                     |                          | (possible alternative names:|
   124 |                     |                          | (possible alternative names:|
   124 |                     |                          | mislead, naive, unaware,    |
   125 |                     |                          | mislead, naive, unaware,    |
   125 |                     |                          | mindless, disenchanting)    |
   126 |                     |                          | mindless, disenchanting)    |
   126 |                     |                          |                             |
   127 |                     |                          |                             |
   127 |                     |                          +-----------------------------+
   128 |                     |                          +-----------------------------+
   128 |                     |                          | **divergent**               |
   129 |                     |                          | **content-divergent**       |
   129 |                     |                          |                             |
   130 |                     |                          |                             |
   130 |                     |                          | *divergent*   is changeset  |
   131 |                     |                          | *content-divergent*   is a  |
   131 |                     |                          | that appears when multiple  |
   132 |                     |                          | changeset that appears when |
   132 |                     |                          | changesets are successors   |
   133 |                     |                          | multiple changesets are     |
   133 |                     |                          | of the same precursor.      |
   134 |                     |                          | successors of the same      |
   134 |                     |                          |                             |
   135 |                     |                          | predecessor.                |
   135 |                     |                          | *divergent*   are solved    |
   136 |                     |                          |                             |
   136 |                     |                          | through a three ways merge  |
   137 |                     |                          | *content-divergent*   are   |
   137 |                     |                          | between the two             |
   138 |                     |                          | solved through a three way  |
   138 |                     |                          | *divergent*   ,             |
   139 |                     |                          | merge between the two       |
       
   140 |                     |                          | *content-divergent*   ,     |
   139 |                     |                          | using the last "obsolete-   |
   141 |                     |                          | using the last "obsolete-   |
   140 |                     |                          | -common-ancestor" as the    |
   142 |                     |                          | -common-ancestor" as the    |
   141 |                     |                          | base.                       |
   143 |                     |                          | base.                       |
   142 |                     |                          |                             |
   144 |                     |                          |                             |
   143 |                     |                          | (*splitting* is             |
   145 |                     |                          | (*splitting* is             |
   149 |                     |                          | conflicting)                |
   151 |                     |                          | conflicting)                |
   150 |                     |                          |                             |
   152 |                     |                          |                             |
   151 |                     +--------------------------+-----------------------------+
   153 |                     +--------------------------+-----------------------------+
   152 |                     |                                                        |
   154 |                     |                                                        |
   153 |                     | Mutable changesets which are neither *obsolete* or     |
   155 |                     | Mutable changesets which are neither *obsolete* or     |
   154 |                     | *troubled*    are *"ok"*.                              |
   156 |                     | *unstable*    are *"ok"*.                              |
   155 |                     |                                                        |
   157 |                     |                                                        |
   156 |                     | Do we really need a name for it ? *"ok"* is a pretty   |
   158 |                     | Do we really need a name for it ? *"ok"* is a pretty   |
   157 |                     | crappy name :-/ other possibilities are:               |
   159 |                     | crappy name :-/ other possibilities are:               |
   158 |                     |                                                        |
   160 |                     |                                                        |
   159 |                     | - stable (confusing with stable branch)                |
   161 |                     | - stable (confusing with stable branch)                |
   166 |                                                                              |
   168 |                                                                              |
   167 | Changesets in the *public* phases.                                           |
   169 | Changesets in the *public* phases.                                           |
   168 |                                                                              |
   170 |                                                                              |
   169 | Rewriting operation refuse to work on immutable changeset.                   |
   171 | Rewriting operation refuse to work on immutable changeset.                   |
   170 |                                                                              |
   172 |                                                                              |
   171 | Obsolete markers that refer an immutable changeset as precursors have        |
   173 | Obsolete markers that refer an immutable changeset as predecessors have      |
   172 | no effect on the precursors but may have effect on the successors.           |
   174 | no effect on the predecessors but may have effect on the successors.         |
   173 |                                                                              |
   175 |                                                                              |
   174 | When a *mutable* changeset becomes *immutable* (changing its phase from draft|
   176 | When a *mutable* changeset becomes *immutable* (changing its phase from draft|
   175 | to public) it is just *immutable* and loose any property of it's former      |
   177 | to public) it is just *immutable* and loose any property of it's former      |
   176 | state.                                                                       |
   178 | state.                                                                       |
   177 |                                                                              |
   179 |                                                                              |
   224 
   226 
   225 evolve
   227 evolve
   226 ``````
   228 ``````
   227 
   229 
   228 Automatically resolve *troublesome* changesets
   230 Automatically resolve *troublesome* changesets
   229 (*unstable*, *bumped* and *divergent*)
   231 (*orphan*, *phase-divergent* and *content-divergent*)
   230 
   232 
   231 This is an important name as hg pull/push will suggest it the same way it
   233 This is an important name as hg pull/push will suggest it the same way it
   232 suggest merging when you add heads.
   234 suggest merging when you add heads.
   233 
   235 
   234 Alternative names:
   236 Alternative names: