[PATCH STABLE] help: add an help topic about the Changesets obsolescence concept

pierre-yves.david at logilab.fr pierre-yves.david at logilab.fr
Wed Aug 1 06:57:46 CDT 2012


# HG changeset patch
# User Pierre-Yves David <pierre-yves.david at logilab.fr>
# Date 1343822129 -7200
# Branch stable
# Node ID c722b2f123ecb3b30d8454c5b0b61305f3dc4776
# Parent  7d2967de2c04489f9ce64308eb39d8a55d66af7c
help: add an help topic about the Changesets obsolescence concept

Thanks to Dirkjan Ochtman for his help.

diff --git a/mercurial/help.py b/mercurial/help.py
--- a/mercurial/help.py
+++ b/mercurial/help.py
@@ -159,10 +159,11 @@ helptable = sorted([
    (["hgweb"], _("Configuring hgweb"), loaddoc('hgweb')),
    (["glossary"], _("Glossary"), loaddoc('glossary')),
    (["hgignore", "ignore"], _("Syntax for Mercurial Ignore Files"),
     loaddoc('hgignore')),
    (["phases"], _("Working with Phases"), loaddoc('phases')),
+   (["obsolescence"], _("Safely rework and exchange mutable history"), loaddoc('obsolescence')),
 ])
 
 # Map topics to lists of callable taking the current topic help and
 # returning the updated version
 helphooks = {}
diff --git a/mercurial/help/obsolescence.txt b/mercurial/help/obsolescence.txt
new file mode 100644
--- /dev/null
+++ b/mercurial/help/obsolescence.txt
@@ -0,0 +1,66 @@
+Changesets obsolescence
+
+    Obsolescence markers make it possible to mark changesets that have been
+    deleted or supersed in a new version of the changeset.
+
+    Unlike the previous way of handling such changes, by stripping the old
+    changesets from the repository, obsolescence markers can be propagated
+    between repositories. This allows for a safe and simple way of exchanging
+    mutable history and altering it after the fact. Changeset phases are
+    respected, such that only draft and secret changesets can be altered (see
+    :hg:`hg phases` for details).
+
+    Obsolescence is tracked using "obsolete markers", a piece of metadata
+    tracking which changesets have been made obsolete, potential successors for
+    a given changeset, the moment the changeset was marked as obsolete, and the
+    user who performed the rewriting operation. The markers are stored
+    separately from standard changeset data can be exchanged without any of the
+    precursor changesets, preventing unnecessary exchange of obsolescence data.
+
+    The complete set of obsolescence markers describes a history of changeset
+    modifications that is orthogonal to the repository history of file
+    modifications. This changeset history allows for detection and automatic
+    resolution of edge cases arising from multiple users rewriting the same part
+    of history concurrently.
+
+    Current feature status
+    ======================
+
+    This feature is still at an early stage of development. While several core
+    behaviors have been adjusted to take obsolescence markers into account, some
+    parts of Mercurial are still unaware of the new concept.
+
+    We do not recommed using this feature with this version of Mercurial. For
+    the latest developments related to this feature, please consult:
+
+        http://mercurial.selenic.com/wiki/ChangesetsObsolescence
+
+
+    Available in this version
+    =========================
+
+    There is currently no functionality in core Mercurial to create obsolescence
+    markers.  Markers can be created using third-party extensions, and some
+    parts of Mercurial will comply with the markers, enforcing behavior as
+    outlined below:
+
+    Changesets marked as obsolete are:
+
+        - hidden from log,
+        - excluded from push, pull, clone,
+        - selected by the 'obsolete()' revset.
+
+    In some situation you may have non-obsolete changesets descending from
+    obsolete changesets. Such changesets are said to be "unstable":
+
+        - push will refuse to push them without --force,
+        - the 'unstable()' revset will select them,
+        - their obsolete ancestors are displayed by log.
+
+    Obsolete changesets with no non-obsolete descendants are said to be
+    "extinct" and will appear when querying the "extinct()" revset.
+
+    Obsolescence markers will be exchanged between repositories that explicitly
+    assert support for the obsolescence feature (this can currently only be done
+    via an extension).
+
diff --git a/tests/test-help.t b/tests/test-help.t
--- a/tests/test-help.t
+++ b/tests/test-help.t
@@ -116,10 +116,11 @@ Short help:
    glossary      Glossary
    hgignore      Syntax for Mercurial Ignore Files
    hgweb         Configuring hgweb
    merge-tools   Merge Tools
    multirevs     Specifying Multiple Revisions
+   obsolescence  Safely rework and exchange mutable history
    patterns      File Name Patterns
    phases        Working with Phases
    revisions     Specifying Single Revisions
    revsets       Specifying Revision Sets
    subrepos      Subrepositories
@@ -194,10 +195,11 @@ Short help:
    glossary      Glossary
    hgignore      Syntax for Mercurial Ignore Files
    hgweb         Configuring hgweb
    merge-tools   Merge Tools
    multirevs     Specifying Multiple Revisions
+   obsolescence  Safely rework and exchange mutable history
    patterns      File Name Patterns
    phases        Working with Phases
    revisions     Specifying Single Revisions
    revsets       Specifying Revision Sets
    subrepos      Subrepositories
@@ -683,10 +685,11 @@ Test that default list of commands omits
    glossary      Glossary
    hgignore      Syntax for Mercurial Ignore Files
    hgweb         Configuring hgweb
    merge-tools   Merge Tools
    multirevs     Specifying Multiple Revisions
+   obsolescence  Safely rework and exchange mutable history
    patterns      File Name Patterns
    phases        Working with Phases
    revisions     Specifying Single Revisions
    revsets       Specifying Revision Sets
    subrepos      Subrepositories
@@ -779,16 +782,17 @@ Test help hooks
 Test keyword search help
 
   $ hg help -k clone
   Topics:
   
-   config     Configuration Files
-   extensions Using Additional Features
-   glossary   Glossary
-   phases     Working with Phases
-   subrepo    Subrepositories
-   urls       URL Paths
+   config       Configuration Files
+   extensions   Using Additional Features
+   glossary     Glossary
+   obsolescence Safely rework and exchange mutable history
+   phases       Working with Phases
+   subrepo      Subrepositories
+   urls         URL Paths
   
   Commands:
   
    clone  make a copy of an existing repository
    paths  show aliases for remote repositories


More information about the Mercurial-devel mailing list