[PATCH STABLE-V2] 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 12:50:02 CDT 2012
# HG changeset patch
# User Pierre-Yves David <pierre-yves.david at logilab.fr>
# Date 1343837069 -7200
# Branch stable
# Node ID b88624b3a8f59b02dd9a33e4358580488b95e0c3
# 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,12 @@ 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,64 @@
+Obsolescence markers make it possible to mark changesets that have been
+deleted or superset 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 recommend 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-globalopts.t b/tests/test-globalopts.t
--- a/tests/test-globalopts.t
+++ b/tests/test-globalopts.t
@@ -349,10 +349,11 @@ Testing -h/--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
@@ -433,10 +434,11 @@ Testing -h/--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
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