Skip to content

docs: add FAQ section #94

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Aug 5, 2025
Merged

docs: add FAQ section #94

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
afc955b
docs: add FAQ section
shenxianpeng Aug 5, 2025
efad796
docs: update markdown table
shenxianpeng Aug 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,8 @@ A powerful [pre-commit](https://pre-commit.com/) hook for auto-formatting and li
- [Troubleshooting](#troubleshooting)
- [Performance Optimization](#performance-optimization)
- [Verbose Output](#verbose-output)
- [FAQ](#faq)
- [What's the difference between `cpp-linter-hooks` and `mirrors-clang-format`?](#whats-the-difference-between-cpp-linter-hooks-and-mirrors-clang-format)
- [Contributing](#contributing)
- [License](#license)

Expand Down Expand Up @@ -181,6 +183,19 @@ repos:
args: [--style=file, --version=18, --verbose] # Add -v or --verbose for detailed output
```

## FAQ

### What's the difference between [`cpp-linter-hooks`](https://github.com/cpp-linter/cpp-linter-hooks) and [`mirrors-clang-format`](https://github.com/pre-commit/mirrors-clang-format)?

| Feature | [`cpp-linter-hooks`](https://github.com/cpp-linter/cpp-linter-hooks) | [`mirrors-clang-format`](https://github.com/pre-commit/mirrors-clang-format) |
|----------------------------------|:---------------------------------------------------------------------:|:----------------------------------------------------------------------------:|
| Supports `clang-format` and `clang-tidy` | ✅ (`clang-format` & `clang-tidy`) | ✅ (`clang-format` only) |
| Loads style configuration | ✅ via `--version` | ✅ (default behavior) |
| Specify `clang-format` version | ✅ via `--version` | ✅ via `rev` |
| Supports passing code string | ✅ via `--style` | ❌ |
| Verbose output | ✅ via `--verbose` | ❌ |
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

Fix misleading feature descriptions in the comparison table.

  • Line 193 shows “Loads style configuration | ✅ via --version”.
    The --version flag selects the clang tool version, it does not load a style file.
    Style configuration is picked up automatically when a .clang-format file is present, or explicitly with --style=file.

  • Line 195 shows “Supports passing code string | ✅ via --style”.
    --style selects a formatting style; it is unrelated to feeding code via stdin.
    If the intent is “formats code read from stdin ( - )”, spell that out explicitly.

Suggested fix:

-| Loads style configuration        | ✅ via `--version`                                                    | ✅ (default behavior)                                                       |
+| Loads style configuration        | ✅ via `--style=file` (or default `.clang-format`)                     | ✅ (default behavior)                                                       |
-| Supports passing code string     | ✅ via `--style`                                                      | ❌                                                                          |
+| Supports formatting code from stdin | ✅ via `-` (stdin)                                                    | ❌                                                                          |

Correcting these cells prevents confusion for readers comparing the two hooks.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
| Feature | [`cpp-linter-hooks`](https://github.com/cpp-linter/cpp-linter-hooks) | [`mirrors-clang-format`](https://github.com/pre-commit/mirrors-clang-format) |
|----------------------------------|:---------------------------------------------------------------------:|:----------------------------------------------------------------------------:|
| Supports `clang-format` and `clang-tidy` | ✅ (`clang-format` & `clang-tidy`) | ✅ (`clang-format` only) |
| Loads style configuration | ✅ via `--version` | ✅ (default behavior) |
| Specify `clang-format` version | ✅ via `--version` | ✅ via `rev` |
| Supports passing code string | ✅ via `--style` | ❌ |
| Verbose output | ✅ via `--verbose` | ❌ |
| Feature | [`cpp-linter-hooks`](https://github.com/cpp-linter/cpp-linter-hooks) | [`mirrors-clang-format`](https://github.com/pre-commit/mirrors-clang-format) |
|----------------------------------|:---------------------------------------------------------------------:|:----------------------------------------------------------------------------:|
| Supports `clang-format` and `clang-tidy` | ✅ (`clang-format` & `clang-tidy`) | ✅ (`clang-format` only) |
| Loads style configuration | ✅ via `--style=file` (or default `.clang-format`) | ✅ (default behavior) |
| Specify `clang-format` version | ✅ via `--version` | ✅ via `rev` |
| Supports formatting code from stdin | ✅ via `-` (stdin) | ❌ |
| Verbose output | ✅ via `--verbose` | ❌ |
🤖 Prompt for AI Agents 
In README.md around lines 190 to 196, the feature descriptions in the comparison
table are misleading regarding style configuration loading and code string
passing. Update the "Loads style configuration" row to remove "via --version"
and clarify that style configuration is automatically loaded from a
.clang-format file or specified with --style=file. For the "Supports passing
code string" row, replace "via --style" with a clear statement that the tool
supports formatting code read from stdin (using -). This will accurately reflect
the features and avoid confusion.



## Contributing

We welcome contributions! Whether it's fixing issues, suggesting improvements, or submitting pull requests, your support is greatly appreciated.
Expand Down
Loading