[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