Tools: support excluding directories for "make format"

As of [0] `intern/itasc/` is excluded from formatting,
however the formatting script was still running clang-format
on files in this directory.

Support ignoring directories to avoid the overhead of running
clang-format which does nothing.

Also add comments & skip creating paths to convert to spaces when
converting tabs to spaces isn't enabled.

[0]: 77617fce77

tools/utils_maintenance/clang_format_paths.py

@@ -22,6 +22,7 @@ from typing import (
     List,
     Optional,
     Sequence,
+    Set,
     Tuple,
 )
 
@@ -47,12 +48,29 @@ extensions_only_retab = (
     ".sh",
 )
 
-ignore_files = {
-    "intern/cycles/render/sobol.cpp",  # Too heavy for clang-format
+# Add files which are too large/heavy to format.
+ignore_files: Set[str] = set([
+    # Currently empty, looks like.
+    # "intern/cycles/render/sobol.cpp",
+])
+
+# Directories not to format (recursively).
+#
+# Notes:
+# - These directories must also have a `.clang-format` that disables formatting,
+#   so developers who use format-on-save functionality enabled don't have these files formatted on save.
+# - The reason to exclude here is to prevent unnecessary work were the files would run through clang-format
+#   only to do nothing because the `.clang-format` file prevents it.
+ignore_directories = {
+    "intern/itasc"
 }
 
 
 def compute_paths(paths: List[str], use_default_paths: bool) -> List[str]:
+    # The resulting paths:
+    # - Use forward slashes on all systems.
+    # - Are relative to the GIT repo without any `.` or `./` prefix.
+
     # Optionally pass in files to operate on.
     if use_default_paths:
         paths = [
@@ -225,21 +243,30 @@ def main() -> int:
     for p in paths:
         print(" ", p)
 
+    # Notes:
+    # - Paths from GIT always use forward slashes (even on WIN32),
+    #   so there is no need to convert slashes.
+    # - Ensure a trailing slash so a `str.startswith` check can be used.
+    ignore_directories_tuple = tuple(p.rstrip("/") + "/" for p in ignore_directories)
+
     files = [
         f for f in source_files_from_git(paths, args.changed_only)
         if f.endswith(extensions)
         if f not in ignore_files
-    ]
+        if not f.startswith(ignore_directories_tuple)
 
-    # Always operate on all CMAKE files (when expanding tabs and no paths given).
-    files_retab = [
-        f for f in source_files_from_git((".",) if use_default_paths else paths, args.changed_only)
-        if f.endswith(extensions_only_retab)
-        if f not in ignore_files
     ]
 
     if args.expand_tabs:
+        # Always operate on all CMAKE files (when expanding tabs and no paths given).
+        files_retab = [
+            f for f in source_files_from_git((".",) if use_default_paths else paths, args.changed_only)
+            if f.endswith(extensions_only_retab)
+            if f not in ignore_files
+            if not f.startswith(ignore_directories_tuple)
+        ]
         convert_tabs_to_spaces(files + files_retab)
+
     clang_format(files)
 
     if version > VERSION_MAX_RECOMMENDED: