Patchwork D523: revset: improve documentation about ordering handling

login
register
mail settings
Submitter phabricator
Date Aug. 30, 2017, 1:53 p.m.
Message ID <c9404bdfcb38becb37f3a8ae24617e1f@localhost.localdomain>
Download mbox | patch
Permalink /patch/23503/
State Not Applicable
Headers show

Comments

phabricator - Aug. 30, 2017, 1:53 p.m.
This revision was automatically updated to reflect the committed changes.
Closed by commit rHG1ad55da94b5b: revset: improve documentation about ordering handling (authored by quark).

REPOSITORY
  rHG Mercurial

CHANGES SINCE LAST UPDATE
  https://phab.mercurial-scm.org/D523?vs=1390&id=1433

REVISION DETAIL
  https://phab.mercurial-scm.org/D523

AFFECTED FILES
  mercurial/revsetlang.py

CHANGE DETAILS




To: quark, #hg-reviewers, yuja
Cc: mercurial-devel

Patch

diff --git a/mercurial/revsetlang.py b/mercurial/revsetlang.py
--- a/mercurial/revsetlang.py
+++ b/mercurial/revsetlang.py
@@ -260,9 +260,10 @@ 
 
 # Constants for ordering requirement, used in getset():
 #
-# If 'define', any nested functions and operations can change the ordering of
-# the entries in the set. If 'follow', any nested functions and operations
-# should take the ordering specified by the first operand to the '&' operator.
+# 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,
 #
@@ -276,15 +277,28 @@ 
 #
 # 'any' means the order doesn't matter. For instance,
 #
-#   X & !Y
-#        ^
-#        any
+#   (X & Y) | ancestors(Z)
+#        ^              ^
+#        any            any
+#
+# For 'X & Y', 'X' decides order so the order of 'Y' does not matter. For
+# 'ancesotrs(Z)', Z's order does not matter since 'ancesotrs' does not care
+# about the order of its argument.
 #
-# 'y()' can either enforce its ordering requirement or take the ordering
-# specified by 'x()' because 'not()' doesn't care the order.
-anyorder = 'any'        # don't care the order
-defineorder = 'define'  # should define the order
-followorder = 'follow'  # must follow the current order
+# 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
 
 def _matchonly(revs, bases):
     """