[clang-tidy][docs] Add documentation for Clang-Tidy Automation

clang-tools-extra/docs/clang-tidy/index.rst

@@ -336,6 +336,107 @@ An overview of all the command-line options:
         some-check.SomeOption: 'some value'
       ...
 
+Clang-Tidy Automation
+=====================
+
+:program:`clang-tidy` can analyze multiple source files by specifying them on
+the command line. For larger projects, automation scripts provide additional
+functionality like parallel execution and integration with version control
+systems.
+
+Running Clang-Tidy in Parallel
+-------------------------------
+
+:program:`clang-tidy` can process multiple files sequentially, but for projects
+with many source files, the :program:`run-clang-tidy.py` script provides
+parallel execution to significantly reduce analysis time. This script is
+included with clang-tidy and runs :program:`clang-tidy` over all files in a
+compilation database or a specified path concurrently.
+
+The script requires a compilation database (``compile_commands.json``) which
+can be generated by build systems like CMake (using
+``-DCMAKE_EXPORT_COMPILE_COMMANDS=ON``) or by tools like `Bear`_.
+
+The script supports most of the same options as :program:`clang-tidy` itself,
+including ``-checks=``, ``-fix``, ``-header-filter=``, and configuration
+options. Run ``run-clang-tidy.py --help`` for a complete list of available
+options.
+
+Example invocations:
+
+.. code-block:: console
+
+  # Run clang-tidy on all files in the compilation database in parallel
+  $ run-clang-tidy.py -p=build/
+
+  # Run with specific checks and apply fixes
+  $ run-clang-tidy.py -p=build/ -fix -checks=-*,readability-*
+
+  # Run on specific files/directories with header filtering
+  $ run-clang-tidy.py -p=build/ -header-filter=src/ src/
+
+  # Run with parallel execution (uses all CPU cores by default)
+  $ run-clang-tidy.py -p=build/ -j 4
+
+Running Clang-Tidy on Diff
+---------------------------
+
+The :program:`clang-tidy-diff.py` script allows you to run
+:program:`clang-tidy` on the lines that have been modified in your working
+directory or in a specific diff. Importantly, :program:`clang-tidy-diff.py` only reports
+diagnostics for changed lines; :program:`clang-tidy` still analyzes the entire
+file and filters out unchanged lines after analysis, so this does not improve
+performance. This is particularly useful for code reviews and continuous
+integration, as it focuses analysis on the changed code rather than the entire
+codebase.
+
+The script can work with various diff sources:
+
+* Git working directory changes
+* Output from ``git diff``
+* Output from ``svn diff``
+* Patch files
+
+Example invocations:
+
+.. code-block:: console
+
+  # Run clang-tidy on all changes in the working directory
+  $ git diff -U0 --no-color HEAD^ | clang-tidy-diff.py -p1
+
+  # Run with specific checks and apply fixes
+  $ git diff -U0 --no-color HEAD^ | clang-tidy-diff.py -p1 -fix \
+    -checks=-*,readability-*
+
+  # Run on staged changes
+  $ git diff -U0 --no-color --cached | clang-tidy-diff.py -p1
+
+  # Run on changes between two commits
+  $ git diff -U0 --no-color HEAD~2 HEAD | clang-tidy-diff.py -p1
+
+  # Run on a patch file
+  $ clang-tidy-diff.py -p1 < changes.patch
+
+The ``-p1`` option tells the script to strip one level of path prefix from
+the diff, which is typically needed for Git diffs. The script supports most of
+the same options as :program:`clang-tidy` itself, including ``-checks=``,
+``-fix``, ``-header-filter=``, and configuration options.
+
+While :program:`clang-tidy-diff.py` is useful for focusing on recent changes,
+relying solely on it may lead to incomplete analysis. Since the script only
+reports warnings from the modified lines, it may miss issues that are caused
+by the changes but manifest elsewhere in the code. For example, changes that
+only add lines to a function may cause it to violate size limits (e.g.,
+`readability-function-size <checks/readability/function-size.html>`_), but the
+diagnostic will be reported at the function declaration, which may not be in
+the diff and thus filtered out. Modifications to header files may also affect
+many implementation files, but only warnings in the modified header lines will
+be reported.
+
+For comprehensive analysis, especially before merging significant changes,
+consider running :program:`clang-tidy` on the entire affected files or the
+whole project using :program:`run-clang-tidy.py`.
+
 .. _clang-tidy-nolint:
 
 Suppressing Undesired Diagnostics
@@ -458,5 +559,6 @@ example, ``NOLINTBEGIN(check-name)`` can be paired with
 :program:`clang-tidy` will generate a ``clang-tidy-nolint`` error diagnostic if
 any ``NOLINTBEGIN``/``NOLINTEND`` comment violates these requirements.
 
+.. _Bear: https://github.com/rizsotto/Bear
 .. _LibTooling: https://clang.llvm.org/docs/LibTooling.html
 .. _How To Setup Tooling For LLVM: https://clang.llvm.org/docs/HowToSetupToolingForLLVM.html