be-code-style

What I do

Fix C++ code formatting issues in the BE and Cloud modules using the project's clang-format configuration (v16).

When to use me

Before committing BE/Cloud C++ code changes
When CI reports clang-format failures
When you need to check or fix C++ code style

Prerequisites

You need to confirm that the major version of the called clang-format is 16. If the current environment's default does not meet this requirement, try the following:

If .vscode/settings.json exists, use the clang-format.executable item in it.
If it is a worktree directory, use the .vscode/settings.json from the main directory.
Check the path to the compiler toolchain by trying to find it from the PATH environment variable, the current directory, and the main directory's custom_env.sh. Look for a clang-format with the major version number 16 in that path and its parent directory.

Procedure

Step 1: Auto-fix formatting

Run the project's formatting script, which enforces clang-format v16:

build-support/clang-format.sh

This formats all C++ files under be/src, be/test, cloud/src, cloud/test in-place, respecting .clang-format and .clang-format-ignore.

Important: Always use this script instead of invoking clang-format directly. The script checks that clang-format version 16 is installed and exits with an error if the wrong version is found. Using a different version will produce inconsistent formatting.

Step 2: Check-only (no modification)

To verify formatting without modifying files:

build-support/check-format.sh

This outputs a diff of any formatting violations and exits non-zero if there are any.

Step 3: Review and commit

After running clang-format.sh, review the changes with git diff to verify only formatting was changed, then stage and commit.

Key Configuration

File	Purpose
`.clang-format`	Main formatting rules (Google-based, 100 col, 4-space indent)
`.clang-format-ignore`	Files excluded from formatting (third-party, generated)
`build-support/run_clang_format.py`	Python wrapper for parallel execution

Excluded Directories

The following are excluded from formatting (see .clang-format-ignore):

be/src/apache-orc/*, be/src/clucene/*, be/src/gutil/*
be/src/glibc-compatibility/*
Specific third-party vendored files (mustache, sse2neon, utf8_check)
cloud/src/common/defer.h

Troubleshooting

Problem	Solution
`clang-format not found`	Install clang-format v16 or set `CLANG_FORMAT_BINARY` env var
`version is not 16`	Install clang-format v16; on macOS: `brew install llvm@16`
Files not being formatted	Check `.clang-format-ignore` for exclusions