# HG changeset patch
# User Boris Feld <boris.feld@octobus.net>
# Date 1508322983 -7200
# Node ID 4f0d4bc63b8a85cd6f7f03f6ad7aa95f639dde7d
# Parent  e3fbf8e3fef2af8ae07a7be6f8ce833a32995e52
configitems: document the choice of using 'match' instead of 'search'

diff -r e3fbf8e3fef2 -r 4f0d4bc63b8a mercurial/configitems.py
--- a/mercurial/configitems.py	Wed Oct 18 12:26:08 2017 +0200
+++ b/mercurial/configitems.py	Wed Oct 18 12:36:23 2017 +0200
@@ -74,6 +74,17 @@
         # search for a matching generic item
         generics = sorted(self._generics, key=(lambda x: (x.priority, x.name)))
         for item in generics:
+            # we use 'match' instead of 'search' to make the matching simpler
+            # for people unfamiliar with regular expression. Having the match
+            # rooted to the start of the string will produce less surprising
+            # result for user writing simple regex for sub-attribute.
+            #
+            # For example using "color\..*" match produces an unsurprising
+            # result, while using search could suddenly match apparently
+            # unrelated configuration that happens to contains "color."
+            # anywhere. This is a tradeoff where we favor requiring ".*" on
+            # some match to avoid the need to prefix most pattern with "^".
+            # The "^" seems more error prone.
             if item._re.match(key):
                 return item