docs/obs-concept.rst
author Pierre-Yves David <pierre-yves.david@logilab.fr>
Thu, 30 Aug 2012 21:47:09 +0200
branchstable
changeset 539 9555231a66b2
parent 527 b81193ef3488
child 574 4f5562c92630
permissions -rw-r--r--
hgweb: disable branchtip filtering for hgweb hgweb make extensibe use of branchtip we should. - Our branchtip wrapping make the function expensive, killing performance. - We do not filter anything un hgweb yet.
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
519
9825c7da5b54 ensure all file have a copyright notice
Pierre-Yves David <pierre-yves.david@ens-lyon.org>
parents: 357
diff changeset
     1
.. Copyright 2011 Pierre-Yves David <pierre-yves.david@ens-lyon.org>
9825c7da5b54 ensure all file have a copyright notice
Pierre-Yves David <pierre-yves.david@ens-lyon.org>
parents: 357
diff changeset
     2
..                Logilab SA        <contact@logilab.fr>
527
b81193ef3488 docs: add missing blank line after Copyright notice
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 519
diff changeset
     3
184
f047cd4f1235 backout obs-concept.rst changes
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 176
diff changeset
     4
-----------------------------------------------------------
f047cd4f1235 backout obs-concept.rst changes
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 176
diff changeset
     5
Why Do We Need a New Concept
f047cd4f1235 backout obs-concept.rst changes
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 176
diff changeset
     6
-----------------------------------------------------------
166
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
     7
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 234
diff changeset
     8
Current DVCSes are great tools for forging a series of flawless
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 234
diff changeset
     9
changesets on your own. But they perform poorly when it comes to
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 234
diff changeset
    10
**sharing** some work in progress and **collaborating** on such work
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 234
diff changeset
    11
in progress.
166
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    12
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
    13
When people forge a new version of a changeset they actually create a
192
706a3a57b567 docs: Merged obs-concept changes by hand.
Arne Babenhauserheide <bab@draketo.de>
parents: 191 186
diff changeset
    14
new changeset and get rid of the original changeset. Difficulties to
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
    15
collaborate mostly came from the way old content is *removed* from
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
    16
a repository.
166
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    17
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    18
Mercurial Approach: Strip
184
f047cd4f1235 backout obs-concept.rst changes
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 176
diff changeset
    19
-----------------------------------------------------
166
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    20
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
    21
With the current version of mercurial, every changeset that exists in
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
    22
your repository is *visible* and *meaningful*. To delete old
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
    23
(rewritten) changesets, mercurial removes them from the repository
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
    24
storage with an operation called *strip*. After the *stripping*, the
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 234
diff changeset
    25
repository looks as if the changeset never existed.
166
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    26
192
706a3a57b567 docs: Merged obs-concept changes by hand.
Arne Babenhauserheide <bab@draketo.de>
parents: 191 186
diff changeset
    27
This approach is simple and effective except for one big
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
    28
drawback: you can remove changesets from **your repository only**. If
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
    29
a stripped changeset exists in another repository it touches, it will
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
    30
show up again. This is because a shared changeset becomes
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
    31
part of a shared global history. Stripping a changeset from all
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 234
diff changeset
    32
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
    33
166
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    34
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
    35
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
    36
191
0f1b8119a281 Backed out backout changeset f047cd4f1235
Arne Babenhauserheide <bab@draketo.de>
parents: 184
diff changeset
    37
Moreover stripping changesets creates backup bundles. This allows
0f1b8119a281 Backed out backout changeset f047cd4f1235
Arne Babenhauserheide <bab@draketo.de>
parents: 184
diff changeset
    38
restoration of the deleted changesets, but the process is painful.
166
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    39
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    40
Finally, as the repository format is not optimized for deletion. stripping a
191
0f1b8119a281 Backed out backout changeset f047cd4f1235
Arne Babenhauserheide <bab@draketo.de>
parents: 184
diff changeset
    41
changeset may be slow in some situations.
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    42
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
    43
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
    44
interaction with the outer world, which is very unfortunate for a
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
    45
*Distributed* VCS.
166
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    46
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 234
diff changeset
    47
.. [#] various work around exists but they require their own workflows
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 234
diff changeset
    48
   which are distinct from the very elegant basic workflow of
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 234
diff changeset
    49
   Mercurial.
166
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    50
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    51
Git Approach: Overwrite Reference
184
f047cd4f1235 backout obs-concept.rst changes
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 176
diff changeset
    52
-----------------------------------------------------
166
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    53
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
    54
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
    55
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
    56
changesets referenced by a git branch** are *visible* and
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
    57
*meaningful*.
166
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    58
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    59
166
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    60
.. warning:: add a schema::
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    61
166
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    62
        C
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    63
        | B---<foo>
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    64
        |/
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    65
        |
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    66
        A
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    67
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    68
    Only B and A are visible.
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    69
191
0f1b8119a281 Backed out backout changeset f047cd4f1235
Arne Babenhauserheide <bab@draketo.de>
parents: 184
diff changeset
    70
This simplifies the process of getting rid of old changesets. You can
0f1b8119a281 Backed out backout changeset f047cd4f1235
Arne Babenhauserheide <bab@draketo.de>
parents: 184
diff changeset
    71
just leave them in place and move the reference on the new one. You
192
706a3a57b567 docs: Merged obs-concept changes by hand.
Arne Babenhauserheide <bab@draketo.de>
parents: 191 186
diff changeset
    72
can then propagate this change by moving the git-branch on remote host
191
0f1b8119a281 Backed out backout changeset f047cd4f1235
Arne Babenhauserheide <bab@draketo.de>
parents: 184
diff changeset
    73
with the newer version of the marker overwriting the older one.
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    74
191
0f1b8119a281 Backed out backout changeset f047cd4f1235
Arne Babenhauserheide <bab@draketo.de>
parents: 184
diff changeset
    75
This approach goes a bit further but still has a major drawback:
166
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    76
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 234
diff changeset
    77
Because you **overwrite** the git-branch, you have no conflict
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 234
diff changeset
    78
resolution. The last to act wins. This makes collaboration on multiple
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 234
diff changeset
    79
changesets difficult because you can't merge concurrent updates on a
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 234
diff changeset
    80
changeset.
166
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    81
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 234
diff changeset
    82
Every overwrite is a forced operation where the operator says, "yes I
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 234
diff changeset
    83
want this to replace that". In highly distributed environments, a user
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 234
diff changeset
    84
may end up with conflicting references and no proper way to choose.
166
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    85
191
0f1b8119a281 Backed out backout changeset f047cd4f1235
Arne Babenhauserheide <bab@draketo.de>
parents: 184
diff changeset
    86
Because of this way to visualize a repository, git-branches are a core
0f1b8119a281 Backed out backout changeset f047cd4f1235
Arne Babenhauserheide <bab@draketo.de>
parents: 184
diff changeset
    87
part of git, which makes the user interface more complicated and
192
706a3a57b567 docs: Merged obs-concept changes by hand.
Arne Babenhauserheide <bab@draketo.de>
parents: 191 186
diff changeset
    88
constrains moving through history.
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    89
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 234
diff changeset
    90
Finally, even if all older changesets still exist in the repository,
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 234
diff changeset
    91
accesing them is still painful.
166
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    92
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    93
184
f047cd4f1235 backout obs-concept.rst changes
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 176
diff changeset
    94
-----------------------------------------------------
f047cd4f1235 backout obs-concept.rst changes
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 176
diff changeset
    95
The Obsolete Marker Concept
f047cd4f1235 backout obs-concept.rst changes
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 176
diff changeset
    96
-----------------------------------------------------
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    97
166
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
    98
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 234
diff changeset
    99
As none of the concepts was powerful enough to fulfill the need of
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 234
diff changeset
   100
safely rewriting history, including easy sharing and collaboration on
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 234
diff changeset
   101
mutable history, we needed another one.
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   102
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   103
Basic concept
184
f047cd4f1235 backout obs-concept.rst changes
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 176
diff changeset
   104
-----------------------------------------------------
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   105
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   106
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   107
Every history rewriting operation stores the information that old rewritten
192
706a3a57b567 docs: Merged obs-concept changes by hand.
Arne Babenhauserheide <bab@draketo.de>
parents: 191 186
diff changeset
   108
changeset is replaced by newer version in a given set of changesets.
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   109
191
0f1b8119a281 Backed out backout changeset f047cd4f1235
Arne Babenhauserheide <bab@draketo.de>
parents: 184
diff changeset
   110
All basic history rewriting operation can create an appropriate obsolete marker.
161
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
163
92b073d13f2d more doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 161
diff changeset
   113
.. figure:: ./figures/example-1-update.*
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   114
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   115
    *Updating* a changeset
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   116
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   117
    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
   118
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-2-split.*
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
    *Splitting* a changeset in multiple 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 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
   126
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   127
234
d32c07269dcd [doc] fix bad include
Pierre-Yves.David@ens-lyon.org
parents: 228
diff changeset
   128
.. figure:: ./figures/simple-3-merge.*
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   129
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   130
    *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
   131
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   132
    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
   133
234
d32c07269dcd [doc] fix bad include
Pierre-Yves.David@ens-lyon.org
parents: 228
diff changeset
   134
.. figure:: ./figures/simple-4-reorder.*
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   135
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   136
    *Moving* changeset around
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
    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
   139
    ``([A'] obsolete A), ([B'] obsolete B)``
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   140
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
234
d32c07269dcd [doc] fix bad include
Pierre-Yves.David@ens-lyon.org
parents: 228
diff changeset
   143
.. figure:: ./figures/simple-5-delete.*
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   144
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   145
    *Removing* a changeset:
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   146
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   147
    One obselete marker ``([] obsolete B)``
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
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   150
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
   151
changesets to **1** old 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
Basic Usage
184
f047cd4f1235 backout obs-concept.rst changes
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 176
diff changeset
   154
-----------------------------------------------------
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   155
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 234
diff changeset
   156
Obsolete markers create a perpendicular history: **a versioned
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 234
diff changeset
   157
changeset graph**. This means that offers the same features we have
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 234
diff changeset
   158
for versioned files but applied to changeset:
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   159
191
0f1b8119a281 Backed out backout changeset f047cd4f1235
Arne Babenhauserheide <bab@draketo.de>
parents: 184
diff changeset
   160
First: we can display a **coherent view** of the history graph in which only a
192
706a3a57b567 docs: Merged obs-concept changes by hand.
Arne Babenhauserheide <bab@draketo.de>
parents: 191 186
diff changeset
   161
single version of your changesets is displayed by the UI.
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   162
191
0f1b8119a281 Backed out backout changeset f047cd4f1235
Arne Babenhauserheide <bab@draketo.de>
parents: 184
diff changeset
   163
Second, because obsolete changeset content is still **available**. You can 
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   164
you can
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   165
192
706a3a57b567 docs: Merged obs-concept changes by hand.
Arne Babenhauserheide <bab@draketo.de>
parents: 191 186
diff changeset
   166
    * **browse** the content of your obsolete commits,
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   167
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   168
    * **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
   169
192
706a3a57b567 docs: Merged obs-concept changes by hand.
Arne Babenhauserheide <bab@draketo.de>
parents: 191 186
diff changeset
   170
    * **restore** content of previously obsolete changesets.
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   171
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   172
Finally, the obsolete marker can be **exchanged between
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   173
repositories**. You are able to share the result on your history
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   174
rewriting operations with other prople and **collaborate on the
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   175
mutable part of the history**.
161
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
Conflicting history rewriting operation can be detected and
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   178
**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
   179
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   180
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   181
Detecting and solving tricky situations
184
f047cd4f1235 backout obs-concept.rst changes
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 176
diff changeset
   182
-----------------------------------------------------
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   183
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   184
History rewriting can lead to complex situations. The obsolete marker
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   185
introduces a simple representation for this complex reality. But
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   186
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
   187
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
   188
192
706a3a57b567 docs: Merged obs-concept changes by hand.
Arne Babenhauserheide <bab@draketo.de>
parents: 191 186
diff changeset
   189
This section describes possible situations, defines precise sets of
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   190
changesets involved in such situations and explains how the error
192
706a3a57b567 docs: Merged obs-concept changes by hand.
Arne Babenhauserheide <bab@draketo.de>
parents: 191 186
diff changeset
   191
cases can be resolved automatically using the available information.
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   192
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   193
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   194
Obsolete changesets
184
f047cd4f1235 backout obs-concept.rst changes
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 176
diff changeset
   195
````````````````````
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   196
191
0f1b8119a281 Backed out backout changeset f047cd4f1235
Arne Babenhauserheide <bab@draketo.de>
parents: 184
diff changeset
   197
Old changesets left behind by obsolete operation are called **obsolete**.
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   198
191
0f1b8119a281 Backed out backout changeset f047cd4f1235
Arne Babenhauserheide <bab@draketo.de>
parents: 184
diff changeset
   199
With the current version of mercurial, this *obsolete* part is stripped from the
0f1b8119a281 Backed out backout changeset f047cd4f1235
Arne Babenhauserheide <bab@draketo.de>
parents: 184
diff changeset
   200
repository before the end of every rewriting operation.
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   201
163
92b073d13f2d more doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 161
diff changeset
   202
.. figure:: ./figures/error-obsolete.*
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   203
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   204
    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
   205
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 234
diff changeset
   206
    This rebase operation added two obsolete markers from new
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 234
diff changeset
   207
    changesets to old changesets. These two old changesets are now
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 234
diff changeset
   208
    part of the *obsolete* part of the history.
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   209
192
706a3a57b567 docs: Merged obs-concept changes by hand.
Arne Babenhauserheide <bab@draketo.de>
parents: 191 186
diff changeset
   210
In most cases, the obsolete set will be fully hidden to both the UI and
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   211
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
   212
audit history rewriting operations.
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   213
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   214
Unstable changesets
184
f047cd4f1235 backout obs-concept.rst changes
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 176
diff changeset
   215
```````````````````
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   216
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 234
diff changeset
   217
While exploring the possibilities of the obsolete marker a bit
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 234
diff changeset
   218
further, you may end up with *obsolete* changesets which have
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 234
diff changeset
   219
*non-obsolete* children. There is 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
   220
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   221
* 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
   222
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   223
* Use a partial rewriting operation. For example amend on a changeset with
192
706a3a57b567 docs: Merged obs-concept changes by hand.
Arne Babenhauserheide <bab@draketo.de>
parents: 191 186
diff changeset
   224
  children.
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   225
191
0f1b8119a281 Backed out backout changeset f047cd4f1235
Arne Babenhauserheide <bab@draketo.de>
parents: 184
diff changeset
   226
*Non-obsolete* changeset based on *obsolete* one are called **unstable**
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   227
163
92b073d13f2d more doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 161
diff changeset
   228
.. figure:: ./figures/error-unstable.*
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   229
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   230
    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
   231
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 234
diff changeset
   232
    In this situation we cannot consider `B` as *obsolete*. But we
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 234
diff changeset
   233
    have all the necessary data to detect `B` as an *unstable* branch
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 234
diff changeset
   234
    of the history because its parent `A` is *obsolete*. In addition,
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 234
diff changeset
   235
    we have enough data to automatically resolve this instability: we
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 234
diff changeset
   236
    know that the new version of `B` parent (`A`) is `A'`. We can
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 234
diff changeset
   237
    deduce that we should rebase `B` on `A'` to get a stable history
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 234
diff changeset
   238
    again.
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   239
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   240
Proper warnings should be issued when part of the history becomes
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   241
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
   242
automatically suggest a resolution to the user of even carry them out
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 234
diff changeset
   243
for them.
161
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
191
0f1b8119a281 Backed out backout changeset f047cd4f1235
Arne Babenhauserheide <bab@draketo.de>
parents: 184
diff changeset
   246
XXX details on automatic resolution for
161
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
* movement
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   249
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   250
* handling deletion
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   251
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   252
* handling split on multiple head
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   253
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   254
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   255
.. [#] For this to happen one needs to explicitly enable exchange of draft
191
0f1b8119a281 Backed out backout changeset f047cd4f1235
Arne Babenhauserheide <bab@draketo.de>
parents: 184
diff changeset
   256
       changesets. See phase help for details.
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   257
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   258
The two parts of the obsolete set
184
f047cd4f1235 backout obs-concept.rst changes
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 176
diff changeset
   259
``````````````````````````````````````
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   260
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   261
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
   262
changesets:
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   263
191
0f1b8119a281 Backed out backout changeset f047cd4f1235
Arne Babenhauserheide <bab@draketo.de>
parents: 184
diff changeset
   264
* an *obsolete* changeset with no or *obsolete* only descendants is called **extinct**.
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   265
191
0f1b8119a281 Backed out backout changeset f047cd4f1235
Arne Babenhauserheide <bab@draketo.de>
parents: 184
diff changeset
   266
* an *obsolete* changeset with *unstable* descendants is called **suspended**.
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   267
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   268
163
92b073d13f2d more doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 161
diff changeset
   269
.. figure:: ./figures/error-extinct.*
161
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
    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
   272
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   273
    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
   274
    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
   275
    `B` is *unstable* as before.
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
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 234
diff changeset
   278
Because nothing outside the obsolete set default on *extinct*
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 234
diff changeset
   279
changesets, they can be safely hidden in the UI and even garbage
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 234
diff changeset
   280
collected. *Suspended* changesets have to stay visible and available
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 234
diff changeset
   281
until their unstable descendant are rewritten into stable version.
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   282
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   283
191
0f1b8119a281 Backed out backout changeset f047cd4f1235
Arne Babenhauserheide <bab@draketo.de>
parents: 184
diff changeset
   284
Conflicting rewrites
192
706a3a57b567 docs: Merged obs-concept changes by hand.
Arne Babenhauserheide <bab@draketo.de>
parents: 191 186
diff changeset
   285
````````````````````
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
If people start to concurrently edit the same part of the history they will
191
0f1b8119a281 Backed out backout changeset f047cd4f1235
Arne Babenhauserheide <bab@draketo.de>
parents: 184
diff changeset
   288
likely meet conflicting situations when a changeset has been rewritten in two
0f1b8119a281 Backed out backout changeset f047cd4f1235
Arne Babenhauserheide <bab@draketo.de>
parents: 184
diff changeset
   289
different ways.
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   290
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   291
163
92b073d13f2d more doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 161
diff changeset
   292
.. figure:: ./figures/error-conflicting.*
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   293
191
0f1b8119a281 Backed out backout changeset f047cd4f1235
Arne Babenhauserheide <bab@draketo.de>
parents: 184
diff changeset
   294
    Conflicting rewrite of `A` into `A'` and `A''`
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   295
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   296
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
   297
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
   298
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
   299
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
   300
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
   301
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
   302
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   303
.. 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
   304
              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
   305
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   306
Allowing multiple new changesets to obsolete a single one allows to
192
706a3a57b567 docs: Merged obs-concept changes by hand.
Arne Babenhauserheide <bab@draketo.de>
parents: 191 186
diff changeset
   307
distinguish a split changeset from a history rewriting conflict.
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   308
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   309
Reliable history
184
f047cd4f1235 backout obs-concept.rst changes
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 176
diff changeset
   310
``````````````````````
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   311
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 234
diff changeset
   312
Obsolete markers help to smooth rewriting operation process. However
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 234
diff changeset
   313
they do not change the fact that **you should only rewrite the mutable
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 234
diff changeset
   314
part of the history**. The phase concept enforces this rule by
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 234
diff changeset
   315
explicitly defining a public immutable set of changesets. Rewriting
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 234
diff changeset
   316
operations refuse to work on public changesets, but there are still
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 234
diff changeset
   317
some corner cases where previously rewritten changesets are made
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 234
diff changeset
   318
public.
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   319
192
706a3a57b567 docs: Merged obs-concept changes by hand.
Arne Babenhauserheide <bab@draketo.de>
parents: 191 186
diff changeset
   320
Special rules apply for obsolete markers pointing to public changesets:
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   321
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   322
* Public changesets are excluded from the obsolete set (public
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   323
  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
   324
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 234
diff changeset
   325
* *newer* version of a public changeset are called **latecomer** and
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 234
diff changeset
   326
  highlighted as an error case.
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   327
173
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   328
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
   329
*latecomer* tries to rewrite, we can easily compute a smaller
4d44a37d51d1 many fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 166
diff changeset
   330
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
   331
*latecomer*.
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   332
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   333
.. warning:: add a schema
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   334
166
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   335
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   336
Conclusion
184
f047cd4f1235 backout obs-concept.rst changes
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 176
diff changeset
   337
----------------
166
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   338
191
0f1b8119a281 Backed out backout changeset f047cd4f1235
Arne Babenhauserheide <bab@draketo.de>
parents: 184
diff changeset
   339
The 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
   340
history rewriting operations. It is a new type of relation between Mercurial
191
0f1b8119a281 Backed out backout changeset f047cd4f1235
Arne Babenhauserheide <bab@draketo.de>
parents: 184
diff changeset
   341
changesets which tracks the result of history rewriting operations.
166
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   342
191
0f1b8119a281 Backed out backout changeset f047cd4f1235
Arne Babenhauserheide <bab@draketo.de>
parents: 184
diff changeset
   343
This concept is simple to define and provides a very solid base for:
166
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   344
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
- Very fast history rewriting operations,
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   347
191
0f1b8119a281 Backed out backout changeset f047cd4f1235
Arne Babenhauserheide <bab@draketo.de>
parents: 184
diff changeset
   348
- auditable and reversible history rewriting process,
166
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
- clean final history,
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   351
191
0f1b8119a281 Backed out backout changeset f047cd4f1235
Arne Babenhauserheide <bab@draketo.de>
parents: 184
diff changeset
   352
- sharing and collaborating on the mutable part of the history,
166
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   353
191
0f1b8119a281 Backed out backout changeset f047cd4f1235
Arne Babenhauserheide <bab@draketo.de>
parents: 184
diff changeset
   354
- gracefully handling history rewriting conflicts,
166
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   355
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 234
diff changeset
   356
- various history rewriting UI's collaborating with an underlying common API.
166
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   357
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   358
.. list-table:: Comparison on solution [#]_
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   359
   :header-rows: 1
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
   * - Solution
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   362
     - Remove changeset locally
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   363
     - Works on any point of your history
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   364
     - Propagation
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   365
     - Collaboration
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   366
     - Speed
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   367
     - Access to older version
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
   * - Strip
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
   * - Reference
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
   * - Obsolete
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
     - `+`
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   388
     - `++`
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   389
     - `++`
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   390
     - `+`
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   391
     - `+`
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   392
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   393
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   394
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 163
diff changeset
   395
.. [#] 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
   396
       goes to the defended solution.