[PATCH 1 of 6 V3] obsolete: clarify documentation for succcessorssets
Sean Farley
sean.michael.farley at gmail.com
Thu Jan 16 00:34:16 UTC 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 8d89a657625079b8c4e530a37d18b20de89c380e
# Parent 47d0843647d1e32f6af4482867327cec5db11a1f
obsolete: clarify documentation for succcessorssets
diff --git a/mercurial/obsolete.py b/mercurial/obsolete.py
--- a/mercurial/obsolete.py
+++ b/mercurial/obsolete.py
@@ -507,33 +507,41 @@ 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 succeed A as a consistent whole, each revision being only partial
+ replacement. The successors set contains non-obsolete changeset 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
- A')
+ In most cases a changeset A will have zero (e.g. the changeset pruned)
+ elements in its successors set or a successors set that contains a single
+ element (e.g. changeset A replaced by A'). Therefor, these successors sets
+ will look like [()] or [(A',)], respectively.
- When changeset is split, it results successors set containing more than
- a single element. Divergent rewriting will result in multiple successors
- sets.
+ When 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',),
+ (A'')].
+
+ 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,)].
They are returned as a list of tuples containing all valid successors sets.
- Final successors unknown locally are considered plain prune (obsoleted
+ Finally, successors unknown locally are considered plain prune (obsoleted
without successors).
- 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."""
+ 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
mailing list