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

Reply via email to