docs/obs-concept.rst
author Aurelien Campeas <aurelien.campeas@logilab.fr>
Tue, 27 Mar 2012 17:49:34 +0200
changeset 173 4d44a37d51d1
parent 166 8f8a52cd0b9f
child 186 0698376bb13c
permissions -rw-r--r--
many fixes
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
166
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
     1
-----------------------------------------------------------
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
     2
Why Do We Need a New Concept
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
     3
-----------------------------------------------------------
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
     4
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
     5
Current DVCS are great tools to forge a series of flawless changeset on your own.
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
     6
But they perform poorly when it comes to **sharing** some work in progress and
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
     7
**collaborating** on such work in progress.
166
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
     8
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
     9
When people forge a new version of a changeset they actually create a
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
    10
new changeset and get rid of the original changeset. Difficultis to
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
    11
collaborate mostly came from the way old content is *removed* from
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
    12
a repository.
166
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    13
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    14
Mercurial Approach: Strip
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    15
-----------------------------------------------------
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    16
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
    17
With the current version of mercurial, every changeset that exists in
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
    18
your repository is *visible* and *meaningful*. To delete old
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
    19
(rewritten) changesets, mercurial removes them from the repository
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
    20
storage with an operation called *strip*. After the *stripping*, the
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
    21
repository looks like if the changeset never existed.
166
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    22
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
    23
This approach is simple and effective except there is a very big
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
    24
drawback: you can remove changesets from **your repository only**. If
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
    25
a stripped changeset exists in another repository it touches, it will
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
    26
show up again. This is because a shared changeset becomes
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
    27
part of a shared global history. Stripping a changeset from all
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
    28
repositories is at best impractical and in most case impossible!
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    29
166
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    30
As consequence, **you can not rewrite something once you exchange it with
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
    31
others**. The old version will still exist along side the new one [#]_.
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    32
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
    33
However backups are created while stripping a changeset in most
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
    34
cases. This allow restoration of an old changeset but the process is
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
    35
painful.
166
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    36
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
    37
Finally, as the repository format is not optimized for deletion,
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
    38
stripping a changeset may be slow in some situation.
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    39
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
    40
To sum up, the strip approach is very simple but does not handle
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
    41
interaction with the outer world, which is very unfortunate for a
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
    42
*Distributed* VCS.
166
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    43
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
    44
.. [#] various workarounds exist but they are workarounds with their own flow.
166
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    45
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    46
Git Approach: Overwrite Reference
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    47
-----------------------------------------------------
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    48
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
    49
The Git approach to repository structure is a bit more complex: there
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
    50
can be any amount of unrelated changesets in a repository, and **only
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
    51
changesets referenced by a git branch** are *visible* and
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
    52
*meaningful*.
166
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    53
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    54
166
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    55
.. warning:: add a schema::
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    56
166
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    57
        C
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    58
        | B---<foo>
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    59
        |/
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    60
        |
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    61
        A
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    62
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    63
    Only B and A are visible.
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    64
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
    65
This ease the process of getting rid of old changesets. You can just
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
    66
leave them in place and move the reference on the new one. You can
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
    67
then propagate those changes by moving the git-branch on remote host,
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
    68
the newer versions overwritting the older ones.
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    69
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
    70
This approach goes a bit further but still have a major drawback:
166
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    71
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
    72
Because you **overwrite** git-branch you have no conflit resolution. The last
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
    73
to speak wins. This makes collaboration on multiple changesets difficult because
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
    74
you can't merge concurent updates on a changeset.
166
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    75
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
    76
Every overwrite is a forced operation where the operator says "Yes I
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
    77
want this to replace that". On a higly distributed environment, a user may
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
    78
end with conflicting references and with no proper way to choose.
166
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    79
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
    80
Because of this way to visualize a repository, git-branches are a very
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
    81
core part of git. This makes the user interface more complicated and
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
    82
moving through history more constrained.
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    83
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
    84
Finally, even if all older changesets still exist in the repository, accesing them
166
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    85
is still painful.
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    86
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    87
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    88
-----------------------------------------------------
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    89
The Obsolete Marker Concept
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    90
-----------------------------------------------------
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    91
166
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    92
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
    93
As none of these concepts were powerful enough to embrace the need to
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
    94
safely share rewritten history we needed another one.
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    95
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    96
Basic concept
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    97
-----------------------------------------------------
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    98
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    99
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   100
Every history rewriting operation stores the information that old rewritten
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   101
changesets has a newer version available in a set of changesets.
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   102
166
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   103
All basic history rewriting operation can create a appropriate obsolete marker.
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   104
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   105
163
92b073d13f2d more doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 161
diff changeset
   106
.. figure:: ./figures/example-1-update.*
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   107
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   108
    *Updating* a changeset
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   109
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   110
    Create one obsolete marker: ``([A'] obsolete A)``
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   111
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   112
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   113
163
92b073d13f2d more doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 161
diff changeset
   114
.. figure:: ./figures/example-2-split.*
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   115
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   116
    *Splitting* a changeset in multiple one
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   117
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   118
    Create one obsolete marker ``([B1, B2] obsolete B)]``
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   119
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   120
163
92b073d13f2d more doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 161
diff changeset
   121
.. figure:: ./figures/example-3-merge.*
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   122
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   123
    *Merging* multiple changeset in a single one
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   124
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   125
    Create two obsolete markers ``([C] obsolete A), ([C] obsolete B)``
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   126
163
92b073d13f2d more doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 161
diff changeset
   127
.. figure:: ./figures/example-4-reorder.*
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   128
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   129
    *Moving* changeset around
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   130
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   131
    Reordering those two changesets need two obsolete markers:
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   132
    ``([A'] obsolete A), ([B'] obsolete B)``
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   133
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   134
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   135
163
92b073d13f2d more doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 161
diff changeset
   136
.. figure:: ./figures/example-5-delete.*
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   137
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   138
    *Removing* a changeset:
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   139
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   140
    One obselete marker ``([] obsolete B)``
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   141
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   142
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   143
To conclude, a single obsolete marker express a relation from **0..n** new
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   144
changesets to **1** old changeset.
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   145
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   146
Basic Usage
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   147
-----------------------------------------------------
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   148
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   149
Obsolete markers create a perpendicular history: **a versionned version of the
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   150
changeset graph**. This means that we can have the same feature we have for
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   151
versioned files but applied to changeset:
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   152
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   153
First: we can display a **coherent view** of the history graph with only a
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   154
single version of your changeset displayed by the UI.
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   155
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   156
Second, because obsolete changeset contents are still **available**,
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   157
you can
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   158
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   159
    * **browse** the contents of your obsolete commits,
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   160
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   161
    * **compare** newer and older versions of a changeset,
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   162
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   163
    * **restore** contents of previously obsolete changesets.
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   164
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   165
Finally, the obsolete marker can be **exchanged between
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   166
repositories**. You are able to share the result on your history
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   167
rewriting operations with other prople and **collaborate on the
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   168
mutable part of the history**.
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   169
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   170
Conflicting history rewriting operation can be detected and
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   171
**resolved** as easily as conflicting changes on a file.
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   172
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   173
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   174
Detecting and solving tricky situations
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   175
-----------------------------------------------------
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   176
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   177
History rewriting can lead to complex situations. The obsolete marker
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   178
introduces a simple representation for this complex reality. But
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   179
people using complex workflows will one day or another have to face
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   180
the intrinsic complexity of some real-world situation.
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   181
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   182
This section describes possible situations, define precise sets of
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   183
changesets involved in such situations and explains how the error
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   184
cases can be automatically resolved using available information.
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   185
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   186
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   187
Obsolete changesets
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   188
````````````````````
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   189
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   190
Old changesets left behind by obsolete operation are said **obsolete**.
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   191
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   192
With the current version of mercurial, this *obsolete* part is
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   193
stripped from the repository before the end of every rewritting
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   194
operation.
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   195
163
92b073d13f2d more doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 161
diff changeset
   196
.. figure:: ./figures/error-obsolete.*
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   197
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   198
    Rebasing `B` and `C` on `A` (as `B'`, `C'`)
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   199
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   200
    This rebase operation added two obsolete markers from new changesets to old
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   201
    changesets. These Two old changesets are now part of the *obsolete* part of the
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   202
    history.
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   203
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   204
In most cases the obsolete set will be fully hidden to both the UI and
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   205
discovery, hence users do not have to care about them unless they want to
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   206
audit history rewriting operations.
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   207
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   208
Unstable changesets
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   209
```````````````````
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   210
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   211
While exploring the obsolete marker possibility a bit further you may
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   212
end up with *obsolete* changeset with *non-obsolete* children. There
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   213
are two common ways to achieve this:
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   214
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   215
* Pull a changeset based of an old version of a changeset [#]_.
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   216
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   217
* Use a partial rewriting operation. For example amend on a changeset with
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   218
  childrens.
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   219
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   220
*Non-obsolete* changeset based on *obsolete* one are said **unstable**
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   221
163
92b073d13f2d more doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 161
diff changeset
   222
.. figure:: ./figures/error-unstable.*
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   223
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   224
    Amend `A` into `A'` leaving `B` behind.
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   225
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   226
    In this situation we can not consider `B` as *obsolete*.  But we have all
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   227
    necessary data to detect `B` as an *unstable* branch of the history because
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   228
    its parent `A` is *obsolete*. In addition, we have enough data to
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   229
    automatically resolve this instability: we know that the new version of `B`
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   230
    parent (`A`) is `A'`, We can deduce that we should rebase `B` on `A'` to get
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   231
    a stable history again.
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   232
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   233
Proper warnings should be issued when part of the history becomes
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   234
unstable. The UI will be able to use the obsolete marker to
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   235
automatically suggest a resolution to the user of even carry them out
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   236
for him.
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   237
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   238
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   239
XXX details automatic resolution for
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   240
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   241
* movement
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   242
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   243
* handling deletion
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   244
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   245
* handling split on multiple head
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   246
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   247
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   248
.. [#] For this to happen one needs to explicitly enable exchange of draft
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   249
       changeset. See phase help for details.
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   250
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   251
The two parts of the obsolete set
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   252
``````````````````````````````````````
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   253
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   254
The previous section shows that there could be two kinds of *obsolete*
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   255
changesets:
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   256
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   257
* *obsolete* changeset with no or *obsolete* only descendants, said **extinct**.
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   258
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   259
* *obsolete* changeset with *unstable* descendants, said **suspended**.
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   260
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   261
163
92b073d13f2d more doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 161
diff changeset
   262
.. figure:: ./figures/error-extinct.*
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   263
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   264
    Amend `A` and `C` leaving `B` behind.
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   265
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   266
    In this example we have two *obsolete* changesets: `C` with no *unstable*
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   267
    children is *extinct*. `A` with *unstable* descendant (`B`) is *suspended*.
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   268
    `B` is *unstable* as before.
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   269
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   270
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   271
Because nothing outside the obsolete set default on *extinct* changesets, they
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   272
can be safely hidden in the UI and even garbage collected. *Suspended* changeset
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   273
have to stay visible and available until they unstable descendant are rewritten
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   274
in stable version.
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   275
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   276
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   277
Conflicting rewriting
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   278
``````````````````````
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   279
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   280
If people start to concurrently edit the same part of the history they will
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   281
likely meet conflicting situations when a changeset have been rewritten in two
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   282
different versions.
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   283
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   284
163
92b073d13f2d more doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 161
diff changeset
   285
.. figure:: ./figures/error-conflicting.*
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   286
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   287
    Conflicting rewriting of `A` into `A'` and `A''`
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   288
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   289
This kind of conflict is easy to detect with an obsolete marker
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   290
because an obsolete changeset can have more than one new version. It
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   291
may be seen as the multiple heads case. Mercurial warns you about this
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   292
on pull. It is resolved the same way by a merge of A' and A'' that
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   293
will keep the same parent than `A'` and `A''` with two obsolete
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   294
markers pointing to both `A` and `A'`
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   295
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   296
.. warning::  TODO: Add a schema of the resolution. (merge A' and A'' with A as
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   297
              ancestor and graft the result of A^)
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   298
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   299
Allowing multiple new changesets to obsolete a single one allows to
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   300
distinguish a split changeset from an history rewriting conflict.
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   301
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   302
Reliable history
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   303
``````````````````````
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   304
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   305
Obsolete marker really help to smooth rewriting operation process. However they
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   306
do not change the fact that **you should only rewrite the mutable part of the
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   307
history**. The phase concept enforce this rules by explicitly defining a
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   308
public immutable set of changeset. Rewriting operation refuse to work on
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   309
public changeset, but they is still some corner case where changesets
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   310
rewritten in the past are made public.
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   311
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   312
Special rules apply for obsolete marker pointing to public changeset:
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   313
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   314
* Public changesets are excluded from the obsolete set (public
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   315
  changesets are never hidden or candidate to garbage collection)
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   316
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   317
* *newer* version of a public changeset are said **latecomer** and highlighted as
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   318
  an error case.
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   319
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   320
Solving such an error is easy. Because we know what changeset a
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   321
*latecomer* tries to rewrite, we can easily compute a smaller
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   322
changeset containing only the change from the old *public* to the new
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   323
*latecomer*.
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   324
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   325
.. warning:: add a schema
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   326
166
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   327
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   328
Conclusion
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   329
----------------
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   330
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   331
Obsolete marker is a powerful concept that allows mercurial to safely handle
166
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   332
history rewriting operations. It is a new type of relation between Mercurial
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   333
changesets that track the result of history rewriting operations.
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   334
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   335
This concept is simple to define and provides a very solid base to:
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   336
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   337
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   338
- Very fast history rewriting operations,
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   339
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   340
- auditable and reversible history rewritting process,
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   341
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   342
- clean final history,
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   343
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   344
- share and collaborate on mutable part of the history,
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   345
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   346
- gracefully handle history rewriting conflict,
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   347
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   348
- allows various history rewriting UI to collaborate with a underlying common API.
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   349
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   350
.. list-table:: Comparison on solution [#]_
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   351
   :header-rows: 1
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   352
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   353
   * - Solution
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   354
     - Remove changeset locally
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   355
     - Works on any point of your history
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   356
     - Propagation
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   357
     - Collaboration
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   358
     - Speed
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   359
     - Access to older version
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   360
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   361
   * - Strip
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   362
     - `+`
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   363
     - `+`
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   364
     - \
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   365
     - \ 
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   366
     - \ 
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   367
     - `- -`
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   368
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   369
   * - Reference
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   370
     - `+`
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   371
     - \ 
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   372
     - `+`
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   373
     - \ 
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   374
     - `+`
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   375
     - `-`
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   376
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   377
   * - Obsolete
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   378
     - `+`
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   379
     - `+`
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   380
     - `++`
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   381
     - `++`
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   382
     - `+`
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   383
     - `+`
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   384
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   385
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   386
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   387
.. [#] To preserve good tradition in comparison table, an overwhelming advantage
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   388
       goes to the defended solution.