[PATCH 7 of 7] dirstate: improve documentation and readability of match and ignore in the walker

[Mads Kiilerich]

# HG changeset patch
# User Mads Kiilerich <madski at unity3d.com>
# Date 1380816081 -7200
#      Thu Oct 03 18:01:21 2013 +0200
# Node ID 8285d8e8c15bb119a388ef481613a5fffceaa6d9
# Parent  c451c290c556b97efa39c1c2bc65d5cccf76cddc
dirstate: improve documentation and readability of match and ignore in the walker

diff --git a/mercurial/dirstate.py b/mercurial/dirstate.py
--- a/mercurial/dirstate.py
+++ b/mercurial/dirstate.py
@@ -596,7 +596,7 @@ class dirstate(object):
                 kind = getkind(st.st_mode)
                 if kind == dirkind:
                     if nf in dmap:
-                        #file deleted on disk but still in dirstate
+                        # file replaced by dir on disk but still in dirstate
                         results[nf] = None
                     if matchedir:
                         matchedir(nf)
@@ -607,10 +607,10 @@ class dirstate(object):
                     badfn(ff, badtype(kind))
                     if nf in dmap:
                         results[nf] = None
-            except OSError, inst:
-                if nf in dmap: # does it exactly match a file?
+            except OSError, inst: # nf not found on disk - it is dirstate only
+                if nf in dmap: # does it exactly match a missing file?
                     results[nf] = None
-                else: # does it match a directory?
+                else: # does it match a missing directory?
                     prefix = nf + "/"
                     for fn in dmap:
                         if fn.startswith(prefix):
@@ -638,13 +638,14 @@ class dirstate(object):
         # implementation doesn't use it at all. This satisfies the contract
         # because we only guarantee a "maybe".
 
-        ignore = self._ignore
-        dirignore = self._dirignore
         if ignored:
             ignore = util.never
             dirignore = util.never
-        elif not unknown:
-            # if unknown and ignored are False, skip step 2
+        elif unknown:
+            ignore = self._ignore
+            dirignore = self._dirignore
+        else:
+            # if not unknown and not ignored, drop dir recursion and step 2
             ignore = util.always
             dirignore = util.always
 
@@ -720,8 +721,11 @@ class dirstate(object):
             del results[s]
         del results['.hg']
 
-        # step 3: report unseen items in the dmap hash
+        # step 3: visit remaining files from dmap
         if not skipstep3 and not exact:
+            # If a dmap file is not in results yet, it was either
+            # a) not matching matchfn b) ignored, c) missing, or d) under a
+            # symlink directory.
             if not results and matchalways:
                 visit = dmap.keys()
             else:
@@ -729,9 +733,10 @@ class dirstate(object):
             visit.sort()
 
             if unknown:
-                # unknown == True means we walked the full directory tree above.
-                # So if a file is not seen it was either a) not matching matchfn
-                # b) ignored, c) missing, or d) under a symlink directory.
+                # unknown == True means we walked all dirs under the roots
+                # that wasn't ignored, and everything that matched was stat'ed
+                # and is already in results.
+                # The rest must thus be ignored or under a symlink.
                 audit_path = pathutil.pathauditor(self._root)
 
                 for nf in iter(visit):
@@ -740,15 +745,17 @@ class dirstate(object):
                     if audit_path.check(nf):
                         try:
                             results[nf] = lstat(join(nf))
+                            # file was just ignored, no links, and exists
                         except OSError:
                             # file doesn't exist
                             results[nf] = None
                     else:
                         # It's either missing or under a symlink directory
+                        # which we in this case report as missing
                         results[nf] = None
             else:
                 # We may not have walked the full directory tree above,
-                # so stat everything we missed.
+                # so stat and check everything we missed.
                 nf = iter(visit).next
                 for st in util.statfiles([join(i) for i in visit]):
                     results[nf()] = st