[PATCH 1 of 6 V4] obsolete: clarify documentation for succcessorssets
sean.michael.farley at gmail.com
Fri Jan 17 14:14:27 CST 2014
# HG changeset patch
# User Sean Farley <sean.michael.farley at gmail.com>
# Date 1389831252 21600
# Wed Jan 15 18:14:12 2014 -0600
# Node ID d21666df8cd1144a799114bb281810602f0cbb88
# Parent 6545770bd37991b4ff0400479455a6e3ffa5976b
obsolete: clarify documentation for succcessorssets
diff --git a/mercurial/obsolete.py b/mercurial/obsolete.py
@@ -507,33 +507,45 @@ def foreground(repo, nodes):
def successorssets(repo, initialnode, cache=None):
"""Return all set of successors of initial nodes
- Successors set of changeset A are a group of revision that succeed A. It
- succeed A as a consistent whole, each revision being only partial
- replacement. Successors set contains non-obsolete changeset only.
+ The successors set of a changeset A are a group of revisions that succeed
+ A. It succeeds A as a consistent whole, each revision being only a partial
+ replacement. The successors set contains non-obsolete changesets only.
- In most cases a changeset A have zero (changeset pruned) or a single
- successors set that contains a single successor (changeset A replaced by
+ This function returns the full list of successor sets which is why it
+ returns a list of tuples and not just a single tuple. Each tuple is a valid
+ successors set. Not that (A,) may be a valid successors set for changeset A
+ (see below).
- When changeset is split, it results successors set containing more than
- a single element. Divergent rewriting will result in multiple successors
+ In most cases, a changeset A will have a single element (e.g. the changeset
+ A is replaced by A') in its successors set. Though, it is also common for a
+ changeset A to have no elements in its successor set (e.g. the changeset
+ has been pruned). Therefore, the returned list of successors sets will be
+ [(A',)] or , respectively.
- They are returned as a list of tuples containing all valid successors sets.
+ When a changeset A is split into A' and B', however, it will result in a
+ successors set containing more than a single element, i.e. [(A',B')].
+ Divergent changesets will result in multiple successors sets, i.e. [(A',),
- Final successors unknown locally are considered plain prune (obsoleted
- without successors).
+ If a changeset A is not obsolete, then it will conceptually have no
+ successors set. To distinguish this from a pruned changeset, the successor
+ set will only contain itself, i.e. [(A,)].
- The optional `cache` parameter is a dictionary that may contains
- precomputed successors sets. It is meant to reuse the computation of
- previous call to `successorssets` when multiple calls are made at the same
- time. The cache dictionary is updated in place. The caller is responsible
- for its live spawn. Code that makes multiple calls to `successorssets`
- *must* use this cache mechanism or suffer terrible performances."""
+ Finally, successors unknown locally are considered to be pruned (obsoleted
+ without any successors).
+ The optional `cache` parameter is a dictionary that may contain precomputed
+ successors sets. It is meant to reuse the computation of a previous call to
+ `successorssets` when multiple calls are made at the same time. The cache
+ dictionary is updated in place. The caller is responsible for its live
+ spawn. Code that makes multiple calls to `successorssets` *must* use this
+ cache mechanism or suffer terrible performances.
succmarkers = repo.obsstore.successors
# Stack of nodes we search successors sets for
toproceed = [initialnode]
More information about the Mercurial-devel