https://github.com/HARSHIL2836R updated https://github.com/llvm/llvm-project/pull/153166
>From 6c7a972b2e1d01fccf9cc0d1ef562c11525f7d77 Mon Sep 17 00:00:00 2001 From: HARSHIL2836R <harshilsolanki1...@gmail.com> Date: Tue, 12 Aug 2025 16:22:48 +0530 Subject: [PATCH 1/9] [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 <harshilsolanki1...@gmail.com> Date: Tue, 12 Aug 2025 22:40:01 +0530 Subject: [PATCH 2/9] [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 <harshilsolanki1...@gmail.com> Date: Tue, 12 Aug 2025 22:44:18 +0530 Subject: [PATCH 3/9] [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 <harshilsolanki1...@gmail.com> Date: Wed, 13 Aug 2025 14:36:31 +0530 Subject: [PATCH 4/9] [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 <harshilsolanki1...@gmail.com> Date: Wed, 13 Aug 2025 17:44:07 +0530 Subject: [PATCH 5/9] [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 <harshilsolanki1...@gmail.com> Date: Thu, 14 Aug 2025 10:50:33 +0530 Subject: [PATCH 6/9] [Clang-Tidy][docs] clarify clang-tidy usage with compilation databases Co-authored-by: Baranov Victor <bar.victor.2...@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 <harshilsolanki1...@gmail.com> Date: Thu, 14 Aug 2025 10:51:05 +0530 Subject: [PATCH 7/9] [Clang-Tidy][docs] clarify clang-tidy usage with compilation database Co-authored-by: Baranov Victor <bar.victor.2...@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 <harshilsolanki1...@gmail.com> Date: Thu, 14 Aug 2025 10:54:28 +0530 Subject: [PATCH 8/9] [Clang-Tidy][docs] Remove Technical Details not relevant to users Co-authored-by: Baranov Victor <bar.victor.2...@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. >From 2a7e33cd44388e436cd342583be5ace170703ef4 Mon Sep 17 00:00:00 2001 From: HARSHIL2836R <harshilsolanki1...@gmail.com> Date: Thu, 14 Aug 2025 10:56:28 +0530 Subject: [PATCH 9/9] [clang-tidy][docs] Update run-clang-tidy.py usage examples to include build directory option --- clang-tools-extra/docs/clang-tidy/index.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/clang-tools-extra/docs/clang-tidy/index.rst b/clang-tools-extra/docs/clang-tidy/index.rst index 3acbaf958bcfd..b482a26828ce7 100644 --- a/clang-tools-extra/docs/clang-tidy/index.rst +++ b/clang-tools-extra/docs/clang-tidy/index.rst @@ -361,16 +361,16 @@ Example invocations: .. code-block:: console # Run clang-tidy on all files in the compilation database in parallel - $ run-clang-tidy.py + $ run-clang-tidy.py -p=build/ # Run with specific checks and apply fixes - $ run-clang-tidy.py -fix -checks=-*,readability-* + $ run-clang-tidy.py -p=build/ -fix -checks=-*,readability-* # Run on specific files/directories with header filtering - $ run-clang-tidy.py -header-filter=src/ src/ + $ run-clang-tidy.py -p=build/ -header-filter=src/ src/ # Run with parallel execution (uses all CPU cores by default) - $ run-clang-tidy.py -j 4 + $ run-clang-tidy.py -p=build/ -j 4 Running Clang-Tidy on Diff --------------------------- @@ -422,7 +422,7 @@ 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 +`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. _______________________________________________ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits