[clang-tools-extra] [clang-tidy][docs] Add documentation for Clang-Tidy Automation (PR #153166)
Harshil Solanki via cfe-commits
cfe-commits at lists.llvm.org
Wed Aug 13 22:24:39 PDT 2025
https://github.com/HARSHIL2836R updated https://github.com/llvm/llvm-project/pull/153166
>From 6c7a972b2e1d01fccf9cc0d1ef562c11525f7d77 Mon Sep 17 00:00:00 2001
From: HARSHIL2836R <harshilsolanki1912 at gmail.com>
Date: Tue, 12 Aug 2025 16:22:48 +0530
Subject: [PATCH 1/8] [clang-tidy] Add documentation for running Clang-Tidy on
multiple files
---
clang-tools-extra/docs/clang-tidy/index.rst | 32 +++++++++++++++++++++
1 file changed, 32 insertions(+)
diff --git a/clang-tools-extra/docs/clang-tidy/index.rst b/clang-tools-extra/docs/clang-tidy/index.rst
index b7a366e874130..77f876f2b718d 100644
--- a/clang-tools-extra/docs/clang-tidy/index.rst
+++ b/clang-tools-extra/docs/clang-tidy/index.rst
@@ -41,6 +41,38 @@ parameters file:
$ clang-tidy @parameters_file
+Running Clang-Tidy on Multiple Files
+=====================================
+
+For projects with multiple source files, you can use the :program:`run-clang-tidy.py`
+script to run :program:`clang-tidy` over all files in a compilation database in
+parallel. This script is included with clang-tidy and provides a convenient way
+to analyze entire projects efficiently.
+
+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.
+
+Example invocations:
+
+.. code-block:: console
+
+ # Run clang-tidy on all files in the compilation database
+ $ run-clang-tidy.py
+
+ # Run with specific checks and apply fixes
+ $ run-clang-tidy.py -fix -checks=-*,readability-*
+
+ # Run on specific files/directories with header filtering
+ $ run-clang-tidy.py src/ -header-filter=src/
+
+ # Run with parallel execution (uses all CPU cores by default)
+ $ run-clang-tidy.py -j 4
+
+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.
+
:program:`clang-tidy` has its own checks and can also run Clang Static Analyzer
checks. Each check has a name and the checks to run can be chosen using the
``-checks=`` option, which specifies a comma-separated list of positive and
>From 184da5e6267f3bf2406fdc8de616e1299422c94b Mon Sep 17 00:00:00 2001
From: HARSHIL2836R <harshilsolanki1912 at gmail.com>
Date: Tue, 12 Aug 2025 22:40:01 +0530
Subject: [PATCH 2/8] [Clang-Tidy] Update documentation for running Clang-Tidy
in parallel and automation scripts
---
clang-tools-extra/docs/clang-tidy/index.rst | 74 ++++++++++++---------
1 file changed, 42 insertions(+), 32 deletions(-)
diff --git a/clang-tools-extra/docs/clang-tidy/index.rst b/clang-tools-extra/docs/clang-tidy/index.rst
index 77f876f2b718d..f092f65d7687f 100644
--- a/clang-tools-extra/docs/clang-tidy/index.rst
+++ b/clang-tools-extra/docs/clang-tidy/index.rst
@@ -41,38 +41,6 @@ parameters file:
$ clang-tidy @parameters_file
-Running Clang-Tidy on Multiple Files
-=====================================
-
-For projects with multiple source files, you can use the :program:`run-clang-tidy.py`
-script to run :program:`clang-tidy` over all files in a compilation database in
-parallel. This script is included with clang-tidy and provides a convenient way
-to analyze entire projects efficiently.
-
-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.
-
-Example invocations:
-
-.. code-block:: console
-
- # Run clang-tidy on all files in the compilation database
- $ run-clang-tidy.py
-
- # Run with specific checks and apply fixes
- $ run-clang-tidy.py -fix -checks=-*,readability-*
-
- # Run on specific files/directories with header filtering
- $ run-clang-tidy.py src/ -header-filter=src/
-
- # Run with parallel execution (uses all CPU cores by default)
- $ run-clang-tidy.py -j 4
-
-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.
-
:program:`clang-tidy` has its own checks and can also run Clang Static Analyzer
checks. Each check has a name and the checks to run can be chosen using the
``-checks=`` option, which specifies a comma-separated list of positive and
@@ -363,6 +331,47 @@ 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 or by using a compilation database. 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
+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
+
+ # Run with specific checks and apply fixes
+ $ run-clang-tidy.py -fix -checks=-*,readability-*
+
+ # Run on specific files/directories with header filtering
+ $ run-clang-tidy.py -header-filter=src/ src/
+
+ # Run with parallel execution (uses all CPU cores by default)
+ $ run-clang-tidy.py -j 4
+
.. _clang-tidy-nolint:
Suppressing Undesired Diagnostics
@@ -485,5 +494,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
>From f931f3ac191a9aa6311c0cd7f8f41f81c91af492 Mon Sep 17 00:00:00 2001
From: HARSHIL2836R <harshilsolanki1912 at gmail.com>
Date: Tue, 12 Aug 2025 22:44:18 +0530
Subject: [PATCH 3/8] [Clang-Tidy] Add documentation for running Clang-Tidy on
diffs
---
clang-tools-extra/docs/clang-tidy/index.rst | 40 +++++++++++++++++++++
1 file changed, 40 insertions(+)
diff --git a/clang-tools-extra/docs/clang-tidy/index.rst b/clang-tools-extra/docs/clang-tidy/index.rst
index f092f65d7687f..eedadcb8161d2 100644
--- a/clang-tools-extra/docs/clang-tidy/index.rst
+++ b/clang-tools-extra/docs/clang-tidy/index.rst
@@ -372,6 +372,46 @@ Example invocations:
# Run with parallel execution (uses all CPU cores by default)
$ run-clang-tidy.py -j 4
+Running Clang-Tidy on Diff
+---------------------------
+
+The :program:`clang-tidy-diff.py` script allows you to run :program:`clang-tidy`
+only on the lines that have been modified in your working directory or in a
+specific diff. 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.
+
.. _clang-tidy-nolint:
Suppressing Undesired Diagnostics
>From 7aac780d31fba6e93d084bcf61098907f72b09ea Mon Sep 17 00:00:00 2001
From: HARSHIL2836R <harshilsolanki1912 at gmail.com>
Date: Wed, 13 Aug 2025 14:36:31 +0530
Subject: [PATCH 4/8] [Clang-Tidy] Enhance documentation for
clang-tidy-diff.py, clarifying its limitations and encouraging comprehensive
analysis
---
clang-tools-extra/docs/clang-tidy/index.rst | 23 ++++++++++++++++++---
1 file changed, 20 insertions(+), 3 deletions(-)
diff --git a/clang-tools-extra/docs/clang-tidy/index.rst b/clang-tools-extra/docs/clang-tidy/index.rst
index eedadcb8161d2..cc00bc445b7e4 100644
--- a/clang-tools-extra/docs/clang-tidy/index.rst
+++ b/clang-tools-extra/docs/clang-tidy/index.rst
@@ -377,9 +377,12 @@ Running Clang-Tidy on Diff
The :program:`clang-tidy-diff.py` script allows you to run :program:`clang-tidy`
only on the lines that have been modified in your working directory or in a
-specific diff. This is particularly useful for code reviews and continuous
-integration, as it focuses analysis on the changed code rather than the entire
-codebase.
+specific diff. Importantly, clang-tidy-diff will only analyze and report
+warnings from the changed lines. The script is essentially a wrapper that
+parses diff output and passes it to :program:`clang-tidy` with the
+``--line-filter`` option, which performs all the actual filtering. 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:
@@ -412,6 +415,20 @@ 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``), 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
>From 0d884d81343e6cdd074fc7d7ac236e46290753dd Mon Sep 17 00:00:00 2001
From: HARSHIL2836R <harshilsolanki1912 at gmail.com>
Date: Wed, 13 Aug 2025 17:44:07 +0530
Subject: [PATCH 5/8] [Clang-Tidy] Clarify behavior of clang-tidy-diff.py
regarding diagnostics and performance
---
clang-tools-extra/docs/clang-tidy/index.rst | 16 +++++++++-------
1 file changed, 9 insertions(+), 7 deletions(-)
diff --git a/clang-tools-extra/docs/clang-tidy/index.rst b/clang-tools-extra/docs/clang-tidy/index.rst
index cc00bc445b7e4..3acbaf958bcfd 100644
--- a/clang-tools-extra/docs/clang-tidy/index.rst
+++ b/clang-tools-extra/docs/clang-tidy/index.rst
@@ -376,13 +376,15 @@ Running Clang-Tidy on Diff
---------------------------
The :program:`clang-tidy-diff.py` script allows you to run :program:`clang-tidy`
-only on the lines that have been modified in your working directory or in a
-specific diff. Importantly, clang-tidy-diff will only analyze and report
-warnings from the changed lines. The script is essentially a wrapper that
-parses diff output and passes it to :program:`clang-tidy` with the
-``--line-filter`` option, which performs all the actual filtering. This is
-particularly useful for code reviews and continuous integration, as it focuses
-analysis on the changed code rather than the entire codebase.
+on the lines that have been modified in your working directory or in a
+specific diff. Importantly, clang-tidy-diff 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. The script
+is essentially a wrapper that parses diff output and passes it to
+:program:`clang-tidy` with the ``--line-filter`` option, which performs all the
+actual filtering. 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:
>From 66268ae3b01892e5a66f517df05149c7a232e73a Mon Sep 17 00:00:00 2001
From: Harshil Solanki <harshilsolanki1912 at gmail.com>
Date: Thu, 14 Aug 2025 10:50:33 +0530
Subject: [PATCH 6/8] [Clang-Tidy][docs] clarify clang-tidy usage with
compilation databases
Co-authored-by: Baranov Victor <bar.victor.2002 at gmail.com>
---
clang-tools-extra/docs/clang-tidy/index.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/clang-tools-extra/docs/clang-tidy/index.rst b/clang-tools-extra/docs/clang-tidy/index.rst
index 3acbaf958bcfd..bce4b78e0d7bd 100644
--- a/clang-tools-extra/docs/clang-tidy/index.rst
+++ b/clang-tools-extra/docs/clang-tidy/index.rst
@@ -335,7 +335,7 @@ Clang-Tidy Automation
=====================
:program:`clang-tidy` can analyze multiple source files by specifying them on the
-command line or by using a compilation database. For larger projects, automation
+command line. For larger projects, automation
scripts provide additional functionality like parallel execution and integration
with version control systems.
>From 72e9ac6697f6dc2031a4d4a92c1e6b48b0bc595d Mon Sep 17 00:00:00 2001
From: Harshil Solanki <harshilsolanki1912 at gmail.com>
Date: Thu, 14 Aug 2025 10:51:05 +0530
Subject: [PATCH 7/8] [Clang-Tidy][docs] clarify clang-tidy usage with
compilation database
Co-authored-by: Baranov Victor <bar.victor.2002 at gmail.com>
---
clang-tools-extra/docs/clang-tidy/index.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/clang-tools-extra/docs/clang-tidy/index.rst b/clang-tools-extra/docs/clang-tidy/index.rst
index bce4b78e0d7bd..a82f4a7c1f775 100644
--- a/clang-tools-extra/docs/clang-tidy/index.rst
+++ b/clang-tools-extra/docs/clang-tidy/index.rst
@@ -346,7 +346,7 @@ Running Clang-Tidy in Parallel
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
-concurrently.
+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``)
>From b30f504c77b5b1803d361d15141c9e4b59e2fa41 Mon Sep 17 00:00:00 2001
From: Harshil Solanki <harshilsolanki1912 at gmail.com>
Date: Thu, 14 Aug 2025 10:54:28 +0530
Subject: [PATCH 8/8] [Clang-Tidy][docs] Remove Technical Details not relevant
to users
Co-authored-by: Baranov Victor <bar.victor.2002 at gmail.com>
---
clang-tools-extra/docs/clang-tidy/index.rst | 6 ++----
1 file changed, 2 insertions(+), 4 deletions(-)
diff --git a/clang-tools-extra/docs/clang-tidy/index.rst b/clang-tools-extra/docs/clang-tidy/index.rst
index a82f4a7c1f775..833d55bf81f9b 100644
--- a/clang-tools-extra/docs/clang-tidy/index.rst
+++ b/clang-tools-extra/docs/clang-tidy/index.rst
@@ -379,10 +379,8 @@ 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, clang-tidy-diff 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. The script
-is essentially a wrapper that parses diff output and passes it to
-:program:`clang-tidy` with the ``--line-filter`` option, which performs all the
-actual filtering. This is particularly useful for code reviews and continuous
+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.
More information about the cfe-commits
mailing list