--- a/mercurial/revset.py Tue Aug 29 11:25:22 2017 +0200
+++ b/mercurial/revset.py Wed Aug 30 22:32:47 2017 +0900
@@ -40,16 +40,53 @@
getargs = revsetlang.getargs
getargsdict = revsetlang.getargsdict
-# constants used as an argument of match() and matchany()
-anyorder = revsetlang.anyorder
-defineorder = revsetlang.defineorder
-followorder = revsetlang.followorder
-
baseset = smartset.baseset
generatorset = smartset.generatorset
spanset = smartset.spanset
fullreposet = smartset.fullreposet
+# Constants for ordering requirement, used in getset():
+#
+# If 'define', any nested functions and operations MAY change the ordering of
+# the entries in the set (but if changes the ordering, it MUST ALWAYS change
+# it). If 'follow', any nested functions and operations MUST take the ordering
+# specified by the first operand to the '&' operator.
+#
+# For instance,
+#
+# X & (Y | Z)
+# ^ ^^^^^^^
+# | follow
+# define
+#
+# will be evaluated as 'or(y(x()), z(x()))', where 'x()' can change the order
+# of the entries in the set, but 'y()', 'z()' and 'or()' shouldn't.
+#
+# 'any' means the order doesn't matter. For instance,
+#
+# (X & Y) | ancestors(Z)
+# ^ ^
+# any any
+#
+# For 'X & Y', 'X' decides order so the order of 'Y' does not matter. For
+# 'ancestors(Z)', Z's order does not matter since 'ancestors' does not care
+# about the order of its argument.
+#
+# Currently, most revsets do not care about the order, so 'define' is
+# equivalent to 'follow' for them, and the resulting order is based on the
+# 'subset' parameter passed down to them:
+#
+# m = revset.match(..., order=defineorder)
+# m(repo, subset)
+# ^^^^^^
+# For most revsets, 'define' means using the order this subset provides
+#
+# There are a few revsets that always redefine the order if 'define' is
+# specified: 'sort(X)', 'reverse(X)', 'x:y'.
+anyorder = 'any' # don't care the order, could be even random-shuffled
+defineorder = 'define' # ALWAYS redefine, or ALWAYS follow the current order
+followorder = 'follow' # MUST follow the current order
+
# helpers
def getset(repo, subset, x, order=defineorder):