Pre-commit Hooks and Code Formatting with clang-format in pybind11-rdp

The pybind11-rdp repository enforces consistent C++ and Python code style by integrating pre-commit hooks with a project-specific clang-format configuration that runs automatically on every commit and in CI.

The cubao/pybind11-rdp project maintains strict code quality standards through automated formatting pipelines. By combining pre-commit hooks with clang-format rules defined in .clang-format, the repository ensures that all C++ bindings and Python code remain consistently styled across all contributions.

Pre-commit Configuration in pybind11-rdp

The orchestration of code quality checks resides in .pre-commit-config.yaml at the repository root. This configuration declares multiple repositories providing hooks that run sequentially before each commit is finalized.

The configuration includes general hygiene checks from the pre-commit-hooks repository, such as check-added-large-files, check-merge-conflict, and trailing-whitespace removal. For Python code, it enforces black for formatting, isort for import sorting, pyupgrade for modernizing syntax to Python 3.6+, and flake8 with bugbear extensions for linting.

Critically for C++ code, the configuration includes the mirrors-clang-format hook from the pre-commit mirrors repository. This hook automatically executes clang-format on all C and C++ source files using the style rules defined in the project's .clang-format file.

clang-format Style Rules

The C++ formatting standards for pybind11-rdp are codified in .clang-format at the repository root. These rules enforce a consistent style that matches the project's C++11 codebase.

Key configuration settings include:

• ColumnLimit: 80 – Restricts lines to 80 characters to maintain readability in split-screen views and terminal environments.
• AlignOperands: true and AlignTrailingComments: true – Ensures that binary operators and end-of-line comments align vertically for improved scanability.
• SpacesInContainerLiterals: true – Adds spaces inside braced initializer lists, enhancing readability of container declarations.
• UseTab: Never and IndentWidth: 4 – Mandates four spaces per indentation level, prohibiting tab characters entirely.
• Custom BraceWrapping rules, including AfterFunction: true and AfterNamespace: true, controlling whether opening braces appear on new lines for function and namespace definitions.

These settings ensure that all C++ bindings in the src/ directory maintain uniform formatting regardless of the original author's editor configuration.

CI Integration and Automated Enforcement

To prevent unformatted code from entering the main branch, pybind11-rdp implements a GitHub Actions workflow defined in .github/workflows/format.yml. This workflow executes the identical pre-commit suite on every push, pull request, and manual workflow dispatch.

The workflow performs three sequential steps:

1. Checks out the repository with submodules using actions/checkout@v4.
2. Configures a Python environment with actions/setup-python@v4.
3. Executes pre-commit/action@v3.0.0, which installs the hooks defined in .pre-commit-config.yaml and runs them against the entire codebase.

If the clang-format hook or any other pre-commit check detects violations, the CI job fails immediately. This enforcement ensures that contributors must resolve formatting issues locally before pull requests can be merged, maintaining consistent code quality without requiring manual review of style issues.

Local Development Workflow

Contributors interact with the formatting pipeline through the pre-commit command-line interface. Setting up the local environment requires a one-time installation of the Git hook script.

To install the pre-commit hooks locally:

pre-commit install

This command writes a script to .git/hooks/pre-commit that executes the configured hooks before every commit. After installation, every git commit automatically triggers clang-format on modified C++ files, black on Python files, and the full suite of hygiene checks.

To manually run all hooks against the entire repository without committing:

pre-commit run -a

This command is useful for verifying formatting compliance before pushing changes or for bulk-fixing files that were modified outside of the pre-commit context.

For formatting individual C++ files without invoking the full pre-commit suite, use clang-format directly:

clang-format -i src/main.cpp

The -i flag performs in-place formatting according to the rules defined in .clang-format. This approach is useful when working in editors that do not have integrated clang-format support or when scripting bulk formatting operations.

Summary

The pybind11-rdp repository maintains code quality through a multi-layered formatting strategy:

• Pre-commit hooks defined in .pre-commit-config.yaml automatically enforce style rules before every commit, including clang-format for C++ and black for Python.
• Project-specific style rules in .clang-format enforce an 80-character line limit, four-space indentation, and consistent brace placement across all C++ bindings.
• CI enforcement via .github/workflows/format.yml prevents merging of unformatted code by running the identical pre-commit suite on every pull request.
• Local workflow integration allows developers to install hooks once with pre-commit install, ensuring consistent formatting across all contributions without manual intervention.

Frequently Asked Questions

How do I set up pre-commit hooks locally for pybind11-rdp?

Install the pre-commit package if you haven't already, then run pre-commit install in the repository root. This writes a Git hook script that executes the checks defined in .pre-commit-config.yaml before every commit. After installation, the hooks run automatically when you execute git commit, blocking the commit if clang-format or other checks detect violations.

What clang-format version does the project use?

The project uses the mirrors-clang-format hook from the pre-commit mirrors repository, which typically tracks recent stable versions of LLVM's clang-format. The specific version is pinned in .pre-commit-config.yaml to ensure reproducible formatting across all developer machines and CI environments. Check the hook revision in that file to determine the exact version currently in use.

How do I fix formatting failures before committing?

If the pre-commit hook rejects your commit due to formatting errors, run pre-commit run -a to execute all hooks against the entire repository. Many hooks, including clang-format and black, automatically fix issues in place. After running this command, stage the modified files with git add and retry your commit. For single-file fixes, you can also run clang-format -i <filename> directly.

Does the CI enforce the same checks as local pre-commit hooks?

Yes, the GitHub Actions workflow defined in .github/workflows/format.yml runs the identical pre-commit suite using pre-commit/action@v3.0.0. This ensures that any code entering the main branch has passed the same clang-format, black, and linting checks that run locally. If the CI job fails, contributors must resolve the formatting issues locally and push the corrected code before the pull request can be merged.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}