From d561507aaf50210700da590f7f4715193cb36f63 Mon Sep 17 00:00:00 2001
From: shenxianpeng <xianpeng.shen@gmail.com>
Date: Fri, 4 Jul 2025 01:20:38 +0300
Subject: [PATCH 01/12] support verbose output

---
 README.md                              | 15 ++++++++++++
 cpp_linter_hooks/clang_format.py       |  3 +++
 testing/pre-commit-config-verbose.yaml |  6 +++++
 testing/run.sh                         |  2 +-
 tests/test_clang_format.py             | 32 ++++++++++++++++++++++++++
 5 files changed, 57 insertions(+), 1 deletion(-)
 create mode 100644 testing/pre-commit-config-verbose.yaml

diff --git a/README.md b/README.md
index cd4b8bf..df047b9 100644
--- a/README.md
+++ b/README.md
@@ -151,6 +151,21 @@ Use -header-filter=.* to display errors from all non-system headers. Use -system
 
 ```
 
+## Troubleshooting
+
+### Debugging `clang-format` hook
+
+If you encounter issues with the clang-format hook (such as exit code 247 or other errors), you can enable verbose output to show the list of processed files.
+
+```yaml
+repos:
+  - repo: https://github.com/cpp-linter/cpp-linter-hooks
+    rev: v0.8.1
+    hooks:
+      - id: clang-format
+        args: [--style=file, --version=18, --verbose]   # Add --verbose for detailed output
+```
+
 ## Contributing
 
 We welcome contributions! Whether it's fixing issues, suggesting improvements, or submitting pull requests, your support is greatly appreciated.
diff --git a/cpp_linter_hooks/clang_format.py b/cpp_linter_hooks/clang_format.py
index cd0eb91..81acae4 100644
--- a/cpp_linter_hooks/clang_format.py
+++ b/cpp_linter_hooks/clang_format.py
@@ -7,6 +7,9 @@
 
 parser = ArgumentParser()
 parser.add_argument("--version", default=DEFAULT_CLANG_VERSION)
+parser.add_argument(
+    "-v", "--verbose", action="store_true", help="Enable verbose output"
+)
 
 
 def run_clang_format(args=None) -> Tuple[int, str]:
diff --git a/testing/pre-commit-config-verbose.yaml b/testing/pre-commit-config-verbose.yaml
new file mode 100644
index 0000000..6730d86
--- /dev/null
+++ b/testing/pre-commit-config-verbose.yaml
@@ -0,0 +1,6 @@
+repos:
+  - repo: .
+    rev: HEAD
+    hooks:
+      - id: clang-format
+        args: [--style=file, --version=16, --verbose]  # test with verbose output
diff --git a/testing/run.sh b/testing/run.sh
index 34725f1..5bc4a22 100644
--- a/testing/run.sh
+++ b/testing/run.sh
@@ -1,7 +1,7 @@
 rm -f result.txt
 git restore testing/main.c
 
-for config in testing/pre-commit-config.yaml testing/pre-commit-config-version.yaml; do
+for config in testing/pre-commit-config.yaml testing/pre-commit-config-version.yaml testing/pre-commit-config-verbose.yaml; do
     pre-commit clean
     pre-commit run -c $config --files testing/main.c | tee -a result.txt || true
     git restore testing/main.c
diff --git a/tests/test_clang_format.py b/tests/test_clang_format.py
index 38a8fe0..4915e32 100644
--- a/tests/test_clang_format.py
+++ b/tests/test_clang_format.py
@@ -64,3 +64,35 @@ def test_run_clang_format_dry_run(args, expected_retval, tmp_path):
     test_file = tmp_path / "main.c"
     ret, _ = run_clang_format(["--dry-run", str(test_file)])
     assert ret == -1  # Dry run should not fail
+
+
+def test_run_clang_format_verbose(tmp_path):
+    """Test that verbose option works and provides detailed output."""
+    # copy test file to tmp_path to prevent modifying repo data
+    test_file = tmp_path / "main.c"
+    test_file.write_bytes(Path("testing/main.c").read_bytes())
+
+    # Test with verbose flag
+    ret, output = run_clang_format(["--verbose", "--style=Google", str(test_file)])
+
+    # Should succeed
+    assert ret == 0
+    # Should have verbose output (will be printed to stderr, not returned)
+    # The function should still return successfully
+    assert test_file.read_text() == Path("testing/good.c").read_text()
+
+
+def test_run_clang_format_verbose_error(tmp_path):
+    """Test that verbose option provides useful error information."""
+    test_file = tmp_path / "main.c"
+    test_file.write_bytes(Path("testing/main.c").read_bytes())
+
+    # Test with verbose flag and invalid style
+    ret, output = run_clang_format(
+        ["--verbose", "--style=InvalidStyle", str(test_file)]
+    )
+
+    # Should fail
+    assert ret != 0
+    # Should have error message in output
+    assert "Invalid value for -style" in output

From c773375737d328089b9b6b39c22a71f2415d946d Mon Sep 17 00:00:00 2001
From: shenxianpeng <xianpeng.shen@gmail.com>
Date: Fri, 4 Jul 2025 01:36:29 +0300
Subject: [PATCH 02/12] fix test failure

---
 README.md                              | 2 +-
 cpp_linter_hooks/clang_format.py       | 6 +++---
 testing/pre-commit-config-verbose.yaml | 5 +++++
 tests/test_clang_format.py             | 2 +-
 4 files changed, 10 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index df047b9..32c00b9 100644
--- a/README.md
+++ b/README.md
@@ -155,7 +155,7 @@ Use -header-filter=.* to display errors from all non-system headers. Use -system
 
 ### Debugging `clang-format` hook
 
-If you encounter issues with the clang-format hook (such as exit code 247 or other errors), you can enable verbose output to show the list of processed files.
+If you encounter issues with the clang-format hook (such as exit code 247 or other errors), you can enable verbose output to show the list of processed files by passing the `-v` or `--verbose` argument in the `args` section.
 
 ```yaml
 repos:
diff --git a/cpp_linter_hooks/clang_format.py b/cpp_linter_hooks/clang_format.py
index 81acae4..b850667 100644
--- a/cpp_linter_hooks/clang_format.py
+++ b/cpp_linter_hooks/clang_format.py
@@ -22,11 +22,11 @@ def run_clang_format(args=None) -> Tuple[int, str]:
     output = ""
     try:
         if "--dry-run" in command:
-            sp = subprocess.run(command, stdout=subprocess.PIPE, encoding="utf-8")
+            sp = subprocess.run(command, stdout=subprocess.PIPE, stderr=subprocess.PIPE, encoding="utf-8")
             retval = -1  # Not a fail just identify it's a dry-run.
-            output = sp.stdout
+            output = sp.stdout + sp.stderr
         else:
-            retval = subprocess.run(command, stdout=subprocess.PIPE).returncode
+            retval = subprocess.run(command, stdout=subprocess.PIPE, stderr=subprocess.PIPE).returncode
         return retval, output
     except FileNotFoundError as stderr:
         retval = 1
diff --git a/testing/pre-commit-config-verbose.yaml b/testing/pre-commit-config-verbose.yaml
index 6730d86..adac182 100644
--- a/testing/pre-commit-config-verbose.yaml
+++ b/testing/pre-commit-config-verbose.yaml
@@ -4,3 +4,8 @@ repos:
     hooks:
       - id: clang-format
         args: [--style=file, --version=16, --verbose]  # test with verbose output
+  - repo: .
+    rev: HEAD
+    hooks:
+      - id: clang-format
+        args: [--style=file, --version=16, -v]  # test with verbose output
diff --git a/tests/test_clang_format.py b/tests/test_clang_format.py
index 4915e32..e7ed8ee 100644
--- a/tests/test_clang_format.py
+++ b/tests/test_clang_format.py
@@ -73,7 +73,7 @@ def test_run_clang_format_verbose(tmp_path):
     test_file.write_bytes(Path("testing/main.c").read_bytes())
 
     # Test with verbose flag
-    ret, output = run_clang_format(["--verbose", "--style=Google", str(test_file)])
+    ret, _ = run_clang_format(["--verbose", "--style=Google", str(test_file)])
 
     # Should succeed
     assert ret == 0

From fb2513336be4b34417f57b804e873916cd906cda Mon Sep 17 00:00:00 2001
From: shenxianpeng <xianpeng.shen@gmail.com>
Date: Fri, 4 Jul 2025 01:37:28 +0300
Subject: [PATCH 03/12] fix lint failure

---
 cpp_linter_hooks/clang_format.py | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/cpp_linter_hooks/clang_format.py b/cpp_linter_hooks/clang_format.py
index b850667..c081ea2 100644
--- a/cpp_linter_hooks/clang_format.py
+++ b/cpp_linter_hooks/clang_format.py
@@ -22,11 +22,18 @@ def run_clang_format(args=None) -> Tuple[int, str]:
     output = ""
     try:
         if "--dry-run" in command:
-            sp = subprocess.run(command, stdout=subprocess.PIPE, stderr=subprocess.PIPE, encoding="utf-8")
+            sp = subprocess.run(
+                command,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                encoding="utf-8",
+            )
             retval = -1  # Not a fail just identify it's a dry-run.
             output = sp.stdout + sp.stderr
         else:
-            retval = subprocess.run(command, stdout=subprocess.PIPE, stderr=subprocess.PIPE).returncode
+            retval = subprocess.run(
+                command, stdout=subprocess.PIPE, stderr=subprocess.PIPE
+            ).returncode
         return retval, output
     except FileNotFoundError as stderr:
         retval = 1

From 63bef2d5052cbf90b0f53b764a99e8b09fbd3cde Mon Sep 17 00:00:00 2001
From: shenxianpeng <xianpeng.shen@gmail.com>
Date: Fri, 4 Jul 2025 01:50:01 +0300
Subject: [PATCH 04/12] refactor clang-format

---
 cpp_linter_hooks/clang_format.py | 60 ++++++++++++++++++++++----------
 1 file changed, 42 insertions(+), 18 deletions(-)

diff --git a/cpp_linter_hooks/clang_format.py b/cpp_linter_hooks/clang_format.py
index c081ea2..29dea46 100644
--- a/cpp_linter_hooks/clang_format.py
+++ b/cpp_linter_hooks/clang_format.py
@@ -1,4 +1,5 @@
 import subprocess
+import sys
 from argparse import ArgumentParser
 from typing import Tuple
 
@@ -16,35 +17,58 @@ def run_clang_format(args=None) -> Tuple[int, str]:
     hook_args, other_args = parser.parse_known_args(args)
     path = ensure_installed("clang-format", hook_args.version)
     command = [str(path), "-i"]
+
+    # Add verbose flag if requested
+    if hook_args.verbose:
+        command.append("--verbose")
+
     command.extend(other_args)
 
-    retval = 0
-    output = ""
     try:
+        # Run the clang-format command with captured output
+        sp = subprocess.run(
+            command,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            encoding="utf-8",
+        )
+
+        # Combine stdout and stderr for complete output
+        output = (sp.stdout or "") + (sp.stderr or "")
+
+        # Handle special case for dry-run mode
         if "--dry-run" in command:
-            sp = subprocess.run(
-                command,
-                stdout=subprocess.PIPE,
-                stderr=subprocess.PIPE,
-                encoding="utf-8",
-            )
-            retval = -1  # Not a fail just identify it's a dry-run.
-            output = sp.stdout + sp.stderr
+            retval = -1  # Special code to identify dry-run mode
         else:
-            retval = subprocess.run(
-                command, stdout=subprocess.PIPE, stderr=subprocess.PIPE
-            ).returncode
+            retval = sp.returncode
+
+        # Print verbose information if requested
+        if hook_args.verbose:
+            _print_verbose_info(command, retval, output)
+
         return retval, output
-    except FileNotFoundError as stderr:
-        retval = 1
-        return retval, str(stderr)
+
+    except FileNotFoundError as e:
+        return 1, str(e)
+
+
+def _print_verbose_info(command: list, retval: int, output: str) -> None:
+    """Print verbose debugging information to stderr."""
+    print(f"Command executed: {' '.join(command)}", file=sys.stderr)
+    print(f"Exit code: {retval}", file=sys.stderr)
+    if output.strip():
+        print(f"Output: {output}", file=sys.stderr)
 
 
 def main() -> int:
     retval, output = run_clang_format()
-    if retval != 0:
+
+    # Print output for errors, but not for dry-run mode
+    if retval != 0 and retval != -1 and output.strip():
         print(output)
-    return retval
+
+    # Convert dry-run special code to success
+    return 0 if retval == -1 else retval
 
 
 if __name__ == "__main__":

From ee23d5c639594c53512cf6b57363afe17594c1f6 Mon Sep 17 00:00:00 2001
From: shenxianpeng <xianpeng.shen@gmail.com>
Date: Fri, 4 Jul 2025 02:35:38 +0300
Subject: [PATCH 05/12] update testing run.sh

---
 testing/run.sh | 23 ++++++++++++++++-------
 1 file changed, 16 insertions(+), 7 deletions(-)

diff --git a/testing/run.sh b/testing/run.sh
index 5bc4a22..16db421 100644
--- a/testing/run.sh
+++ b/testing/run.sh
@@ -1,17 +1,26 @@
-rm -f result.txt
+#!/bin/bash
+# 2 Failed cases are expected
+pre-commit clean
+pre-commit run -c testing/pre-commit-config.yaml --files testing/main.c | tee -a result.txt || true
 git restore testing/main.c
 
-for config in testing/pre-commit-config.yaml testing/pre-commit-config-version.yaml testing/pre-commit-config-verbose.yaml; do
-    pre-commit clean
-    pre-commit run -c $config --files testing/main.c | tee -a result.txt || true
-    git restore testing/main.c
-done
+# 10 Failed cases are expected
+pre-commit clean
+pre-commit run -c testing/pre-commit-config-version.yaml --files testing/main.c | tee -a result.txt || true
+git restore testing/main.c
+cat result.txt
+
+# 2 Failed cases are expected
+pre-commit clean
+pre-commit run -c testing/pre-commit-config-verbose.yaml --files testing/main.c | tee -a result.txt || true
+git restore testing/main.c
+cat result.txt
 
 failed_cases=`grep -c "Failed" result.txt`
 
 echo $failed_cases " cases failed."
 
-if [ $failed_cases -eq 9 ]; then
+if [ $failed_cases -eq 10 ]; then
     echo "=============================="
     echo "Test cpp-linter-hooks success."
     echo "=============================="

From 7368f3ba52f9c9e8b36196710011f9c16dd6ba64 Mon Sep 17 00:00:00 2001
From: shenxianpeng <xianpeng.shen@gmail.com>
Date: Fri, 4 Jul 2025 02:41:16 +0300
Subject: [PATCH 06/12] update testing run.sh

---
 testing/run.sh | 16 ++++++++++++++--
 1 file changed, 14 insertions(+), 2 deletions(-)

diff --git a/testing/run.sh b/testing/run.sh
index 16db421..2131324 100644
--- a/testing/run.sh
+++ b/testing/run.sh
@@ -1,20 +1,32 @@
 #!/bin/bash
 # 2 Failed cases are expected
+echo "==========================="
+echo "Test pre-commit-config.yaml"
+echo "==========================="
 pre-commit clean
 pre-commit run -c testing/pre-commit-config.yaml --files testing/main.c | tee -a result.txt || true
 git restore testing/main.c
 
 # 10 Failed cases are expected
+echo "===================================="
+echo "Test pre-commit-config-version.yaml"
+echo "===================================="
 pre-commit clean
 pre-commit run -c testing/pre-commit-config-version.yaml --files testing/main.c | tee -a result.txt || true
 git restore testing/main.c
-cat result.txt
 
 # 2 Failed cases are expected
+echo "===================================="
+echo "Test pre-commit-config-verbose.yaml"
+echo "===================================="
 pre-commit clean
 pre-commit run -c testing/pre-commit-config-verbose.yaml --files testing/main.c | tee -a result.txt || true
 git restore testing/main.c
+
+echo "===================================="
+echo "print result.txt"
 cat result.txt
+echo "===================================="
 
 failed_cases=`grep -c "Failed" result.txt`
 
@@ -24,8 +36,8 @@ if [ $failed_cases -eq 10 ]; then
     echo "=============================="
     echo "Test cpp-linter-hooks success."
     echo "=============================="
-    exit 0
     rm result.txt
+    exit 0
 else
     echo "============================="
     echo "Test cpp-linter-hooks failed."

From a2b664cd9e4d0fb1241ddcbb41d190037965d677 Mon Sep 17 00:00:00 2001
From: shenxianpeng <xianpeng.shen@gmail.com>
Date: Fri, 4 Jul 2025 02:48:27 +0300
Subject: [PATCH 07/12] update testing run.sh

---
 testing/run.sh | 7 ++-----
 1 file changed, 2 insertions(+), 5 deletions(-)

diff --git a/testing/run.sh b/testing/run.sh
index 2131324..b176b06 100644
--- a/testing/run.sh
+++ b/testing/run.sh
@@ -1,5 +1,4 @@
 #!/bin/bash
-# 2 Failed cases are expected
 echo "==========================="
 echo "Test pre-commit-config.yaml"
 echo "==========================="
@@ -7,7 +6,6 @@ pre-commit clean
 pre-commit run -c testing/pre-commit-config.yaml --files testing/main.c | tee -a result.txt || true
 git restore testing/main.c
 
-# 10 Failed cases are expected
 echo "===================================="
 echo "Test pre-commit-config-version.yaml"
 echo "===================================="
@@ -15,7 +13,6 @@ pre-commit clean
 pre-commit run -c testing/pre-commit-config-version.yaml --files testing/main.c | tee -a result.txt || true
 git restore testing/main.c
 
-# 2 Failed cases are expected
 echo "===================================="
 echo "Test pre-commit-config-verbose.yaml"
 echo "===================================="
@@ -23,10 +20,10 @@ pre-commit clean
 pre-commit run -c testing/pre-commit-config-verbose.yaml --files testing/main.c | tee -a result.txt || true
 git restore testing/main.c
 
-echo "===================================="
+echo "=================================================================================="
 echo "print result.txt"
 cat result.txt
-echo "===================================="
+echo "=================================================================================="
 
 failed_cases=`grep -c "Failed" result.txt`
 

From fcbf65a9284595d6134df544dd305d0efcc48c99 Mon Sep 17 00:00:00 2001
From: shenxianpeng <xianpeng.shen@gmail.com>
Date: Fri, 4 Jul 2025 03:08:03 +0300
Subject: [PATCH 08/12] update README.md

---
 README.md | 65 +++++++++++++++++++++++++++++++------------------------
 1 file changed, 37 insertions(+), 28 deletions(-)

diff --git a/README.md b/README.md
index 32c00b9..facdaff 100644
--- a/README.md
+++ b/README.md
@@ -5,18 +5,25 @@
 [![codecov](https://codecov.io/gh/cpp-linter/cpp-linter-hooks/branch/main/graph/badge.svg?token=L74Z3HZ4Y5)](https://codecov.io/gh/cpp-linter/cpp-linter-hooks)
 [![Test](https://github.com/cpp-linter/cpp-linter-hooks/actions/workflows/test.yml/badge.svg)](https://github.com/cpp-linter/cpp-linter-hooks/actions/workflows/test.yml)
 [![CodeQL](https://github.com/cpp-linter/cpp-linter-hooks/actions/workflows/codeql.yml/badge.svg)](https://github.com/cpp-linter/cpp-linter-hooks/actions/workflows/codeql.yml)
-<!-- [![PyPI - Downloads](https://img.shields.io/pypi/dw/cpp-linter-hooks)](https://pypi.org/project/cpp-linter-hooks/) -->
 
-cpp-linter-hooks is a [pre-commit](https://pre-commit.com/) hook that uses `clang-format` and `clang-tidy` to format C/C++ code.
+A powerful [pre-commit](https://pre-commit.com/) hook that automatically formats and lints your C/C++ code using `clang-format` and `clang-tidy`.
 
-> [!NOTE]
-> This hook automatically downloads specific versions of `clang-format` or `clang-tidy` [static-binaries](https://github.com/cpp-linter/clang-tools-static-binaries) and installs them on your system.
+## Table of Contents
 
-## Usage
+- [Quick Start](#quick-start)
+- [Custom Configuration Files](#custom-configuration-files)
+- [Custom Clang Tool Version](#custom-clang-tool-version)
+- [Troubleshooting](#troubleshooting)
+- [Debugging `clang-format` hook](#debugging-clang-format-hook)
+- [Output](#output)
+  - [clang-format Output](#clang-format-output)
+  - [clang-tidy Output](#clang-tidy-output)
+- [Contributing](#contributing)
+- [License](#license)
 
-To use cpp-linter-hooks, add the following configuration to your `.pre-commit-config.yaml`:
+## Quick Start
 
-### Basic Configuration
+Add this configuration to your `.pre-commit-config.yaml` file:
 
 ```yaml
 repos:
@@ -29,7 +36,7 @@ repos:
         args: [--checks='boost-*,bugprone-*,performance-*,readability-*,portability-*,modernize-*,clang-analyzer-*,cppcoreguidelines-*']
 ```
 
-### Custom Configuration
+### Custom Configuration Files
 
 To use custom configurations like `.clang-format` and `.clang-tidy`:
 
@@ -44,6 +51,8 @@ repos:
         args: [--checks=.clang-tidy] # Loads checks from .clang-tidy file
 ```
 
+### Custom Clang Tool Version
+
 To use specific versions of [clang-tools](https://github.com/cpp-linter/clang-tools-pip?tab=readme-ov-file#supported-versions):
 
 ```yaml
@@ -57,6 +66,8 @@ repos:
         args: [--checks=.clang-tidy, --version=18] # Specifies version
 ```
 
+### Troubleshooting
+
 > [!IMPORTANT]
 > If your `pre-commit` runs longer than expected, it is highly recommended to add `files` in `.pre-commit-config.yaml` to limit the scope of the hook. This helps improve performance by reducing the number of files being checked and avoids unnecessary processing. Here's an example configuration:
 
@@ -81,9 +92,22 @@ pre-commit run --files $(git diff --name-only)
 
 This approach ensures that only modified files are checked, further speeding up the linting process during development.
 
+### Debugging `clang-format` hook
+
+If you encounter issues with the clang-format hook (such as exit code 247 or other errors), you can enable verbose output to show the list of processed files by passing the `-v` or `--verbose` argument in the `args` section.
+
+```yaml
+repos:
+  - repo: https://github.com/cpp-linter/cpp-linter-hooks
+    rev: v0.8.1
+    hooks:
+      - id: clang-format
+        args: [--style=file, --version=18, --verbose]   # Add -v or --verbose for detailed output
+```
+
 ## Output
 
-### clang-format Example
+### clang-format Output
 
 ```bash
 clang-format.............................................................Failed
@@ -106,8 +130,8 @@ Here’s a sample diff showing the formatting applied:
 +  return 0;
 +}
 ```
-
-Use `--dry-run` in `args` of `clang-format` to print instead of changing the format, e.g.:
+> [!NOTE]
+> Use `--dry-run` in `args` of `clang-format` to print instead of changing the format, e.g.:
 
 ```bash
 clang-format.............................................................Failed
@@ -134,7 +158,7 @@ int main() {for (;;) break; printf("Hello world!\n");return 0;}
                                                               ^
 ```
 
-### clang-tidy Example
+### clang-tidy Output
 
 ```bash
 clang-tidy...............................................................Failed
@@ -151,25 +175,10 @@ Use -header-filter=.* to display errors from all non-system headers. Use -system
 
 ```
 
-## Troubleshooting
-
-### Debugging `clang-format` hook
-
-If you encounter issues with the clang-format hook (such as exit code 247 or other errors), you can enable verbose output to show the list of processed files by passing the `-v` or `--verbose` argument in the `args` section.
-
-```yaml
-repos:
-  - repo: https://github.com/cpp-linter/cpp-linter-hooks
-    rev: v0.8.1
-    hooks:
-      - id: clang-format
-        args: [--style=file, --version=18, --verbose]   # Add --verbose for detailed output
-```
-
 ## Contributing
 
 We welcome contributions! Whether it's fixing issues, suggesting improvements, or submitting pull requests, your support is greatly appreciated.
 
 ## License
 
-cpp-linter-hooks is licensed under the [MIT License](LICENSE)
+This project is licensed under the [MIT License](LICENSE).

From 2842fbf686f960d24af61a7c9567ccbcc17fde14 Mon Sep 17 00:00:00 2001
From: shenxianpeng <xianpeng.shen@gmail.com>
Date: Fri, 4 Jul 2025 03:14:28 +0300
Subject: [PATCH 09/12] update README.md

---
 README.md | 88 ++++++++++++++++++++++++++++---------------------------
 1 file changed, 45 insertions(+), 43 deletions(-)

diff --git a/README.md b/README.md
index facdaff..b39bf74 100644
--- a/README.md
+++ b/README.md
@@ -11,13 +11,14 @@ A powerful [pre-commit](https://pre-commit.com/) hook that automatically formats
 ## Table of Contents
 
 - [Quick Start](#quick-start)
-- [Custom Configuration Files](#custom-configuration-files)
-- [Custom Clang Tool Version](#custom-clang-tool-version)
-- [Troubleshooting](#troubleshooting)
-- [Debugging `clang-format` hook](#debugging-clang-format-hook)
+  - [Custom Configuration Files](#custom-configuration-files)
+  - [Custom Clang Tool Version](#custom-clang-tool-version)
 - [Output](#output)
   - [clang-format Output](#clang-format-output)
   - [clang-tidy Output](#clang-tidy-output)
+- [Troubleshooting](#troubleshooting)
+  - [Performance Optimization](#performance-optimization)
+  - [Verbose Output](#verbose-output)
 - [Contributing](#contributing)
 - [License](#license)
 
@@ -66,45 +67,6 @@ repos:
         args: [--checks=.clang-tidy, --version=18] # Specifies version
 ```
 
-### Troubleshooting
-
-> [!IMPORTANT]
-> If your `pre-commit` runs longer than expected, it is highly recommended to add `files` in `.pre-commit-config.yaml` to limit the scope of the hook. This helps improve performance by reducing the number of files being checked and avoids unnecessary processing. Here's an example configuration:
-
-
-```yaml
-- repo: https://github.com/cpp-linter/cpp-linter-hooks
-  rev: v0.8.1
-  hooks:
-    - id: clang-format
-      args: [--style=file, --version=18]
-      files: ^(src|include)/.*\.(cpp|cc|cxx|h|hpp)$ # Limits to specific dirs and file types
-    - id: clang-tidy
-      args: [--checks=.clang-tidy, --version=18]
-      files: ^(src|include)/.*\.(cpp|cc|cxx|h|hpp)$
-```
-
-Alternatively, if you want to run the hooks manually on only the changed files, you can use the following command:
-
-```bash
-pre-commit run --files $(git diff --name-only)
-```
-
-This approach ensures that only modified files are checked, further speeding up the linting process during development.
-
-### Debugging `clang-format` hook
-
-If you encounter issues with the clang-format hook (such as exit code 247 or other errors), you can enable verbose output to show the list of processed files by passing the `-v` or `--verbose` argument in the `args` section.
-
-```yaml
-repos:
-  - repo: https://github.com/cpp-linter/cpp-linter-hooks
-    rev: v0.8.1
-    hooks:
-      - id: clang-format
-        args: [--style=file, --version=18, --verbose]   # Add -v or --verbose for detailed output
-```
-
 ## Output
 
 ### clang-format Output
@@ -175,6 +137,46 @@ Use -header-filter=.* to display errors from all non-system headers. Use -system
 
 ```
 
+## Troubleshooting
+
+### Performance Optimization
+
+> [!WARNING]
+> If your `pre-commit` runs longer than expected, it is highly recommended to add `files` in `.pre-commit-config.yaml` to limit the scope of the hook. This helps improve performance by reducing the number of files being checked and avoids unnecessary processing. Here's an example configuration:
+
+```yaml
+- repo: https://github.com/cpp-linter/cpp-linter-hooks
+  rev: v0.8.1
+  hooks:
+    - id: clang-format
+      args: [--style=file, --version=18]
+      files: ^(src|include)/.*\.(cpp|cc|cxx|h|hpp)$ # Limits to specific dirs and file types
+    - id: clang-tidy
+      args: [--checks=.clang-tidy, --version=18]
+      files: ^(src|include)/.*\.(cpp|cc|cxx|h|hpp)$
+```
+
+Alternatively, if you want to run the hooks manually on only the changed files, you can use the following command:
+
+```bash
+pre-commit run --files $(git diff --name-only)
+```
+
+This approach ensures that only modified files are checked, further speeding up the linting process during development.
+
+### Verbose Output
+
+If you encounter issues with the `clang-format` hook (such as exit code 247 or other errors), you can enable verbose output to show the list of processed files by passing the `-v` or `--verbose` argument in the `args` section.
+
+```yaml
+repos:
+  - repo: https://github.com/cpp-linter/cpp-linter-hooks
+    rev: v0.8.1
+    hooks:
+      - id: clang-format
+        args: [--style=file, --version=18, --verbose]   # Add -v or --verbose for detailed output
+```
+
 ## Contributing
 
 We welcome contributions! Whether it's fixing issues, suggesting improvements, or submitting pull requests, your support is greatly appreciated.

From 038b12a942aa0f5c4a48f7e416fdbdcbd1c6cfb3 Mon Sep 17 00:00:00 2001
From: shenxianpeng <xianpeng.shen@gmail.com>
Date: Fri, 4 Jul 2025 03:19:17 +0300
Subject: [PATCH 10/12] update project descrtion

---
 README.md      | 2 +-
 pyproject.toml | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index b39bf74..4a95757 100644
--- a/README.md
+++ b/README.md
@@ -6,7 +6,7 @@
 [![Test](https://github.com/cpp-linter/cpp-linter-hooks/actions/workflows/test.yml/badge.svg)](https://github.com/cpp-linter/cpp-linter-hooks/actions/workflows/test.yml)
 [![CodeQL](https://github.com/cpp-linter/cpp-linter-hooks/actions/workflows/codeql.yml/badge.svg)](https://github.com/cpp-linter/cpp-linter-hooks/actions/workflows/codeql.yml)
 
-A powerful [pre-commit](https://pre-commit.com/) hook that automatically formats and lints your C/C++ code using `clang-format` and `clang-tidy`.
+A powerful [pre-commit](https://pre-commit.com/) hook for auto-formatting and linting C/C++ code with `clang-format` and `clang-tidy`.
 
 ## Table of Contents
 
diff --git a/pyproject.toml b/pyproject.toml
index fc9ac2d..8ad28ab 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -6,7 +6,7 @@ requires-python = ">=3.9"
 
 [project]
 name = "cpp_linter_hooks"
-description = "Automatically check c/c++ code with clang-format and clang-tidy"
+description = "Automatically formats and lints C/C++ code using clang-format and clang-tidy"
 readme = "README.md"
 keywords = ["clang", "clang-format", "clang-tidy", "pre-commit", "pre-commit-hooks"]
 license = "MIT"

From 7b520ce36c9d6a0687640f894e828ac7e6067554 Mon Sep 17 00:00:00 2001
From: shenxianpeng <xianpeng.shen@gmail.com>
Date: Fri, 4 Jul 2025 03:23:07 +0300
Subject: [PATCH 11/12] update readme.md

---
 README.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 4a95757..8162b8b 100644
--- a/README.md
+++ b/README.md
@@ -166,7 +166,8 @@ This approach ensures that only modified files are checked, further speeding up
 
 ### Verbose Output
 
-If you encounter issues with the `clang-format` hook (such as exit code 247 or other errors), you can enable verbose output to show the list of processed files by passing the `-v` or `--verbose` argument in the `args` section.
+> [!NOTE]
+> Use `-v` or `--verbose` in `args` of `clang-format` to show the list of processed files e.g.:
 
 ```yaml
 repos:

From e0b7980bda7b1009429d34d1c1d2dfae2416143b Mon Sep 17 00:00:00 2001
From: shenxianpeng <xianpeng.shen@gmail.com>
Date: Fri, 4 Jul 2025 03:28:12 +0300
Subject: [PATCH 12/12] add no cover to main

---
 cpp_linter_hooks/clang_format.py | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/cpp_linter_hooks/clang_format.py b/cpp_linter_hooks/clang_format.py
index 29dea46..de3319f 100644
--- a/cpp_linter_hooks/clang_format.py
+++ b/cpp_linter_hooks/clang_format.py
@@ -61,14 +61,14 @@ def _print_verbose_info(command: list, retval: int, output: str) -> None:
 
 
 def main() -> int:
-    retval, output = run_clang_format()
+    retval, output = run_clang_format()  # pragma: no cover
 
     # Print output for errors, but not for dry-run mode
-    if retval != 0 and retval != -1 and output.strip():
+    if retval != 0 and retval != -1 and output.strip():  # pragma: no cover
         print(output)
 
     # Convert dry-run special code to success
-    return 0 if retval == -1 else retval
+    return 0 if retval == -1 else retval  # pragma: no cover
 
 
 if __name__ == "__main__":