Clang-Format

clang-format makes source layout a repository policy rather than a per-author preference. It formats supported languages from a syntactic token stream, so indentation, wrapping, and many spacing decisions are reproducible. It does not establish naming, API, ownership, or behavioral correctness; review must still examine those semantic concerns.

Establishing Repository Policy #

Commit a .clang-format file at the repository root. With --style=file, clang-format searches from each input file toward its ancestor directories and selects the closest .clang-format or _clang-format. A nested directory can therefore deliberately override a root policy, but an accidental nested file changes the result for that subtree.

Use explicit YAML, including the base style when a preset supplies defaults:

---
BasedOnStyle: LLVM
IndentWidth: 4
ColumnLimit: 100
SortIncludes: CaseSensitive

LLVM, Google, Chromium, Mozilla, WebKit, Microsoft, and GNU are built-in base styles. A preset name is not a stable repository policy: new clang-format versions can add options or alter defaults. Generate a complete version-specific starting point with clang-format --style=LLVM --dump-config, review it, and commit the intended options. Pin the formatter version in developer and CI environments when byte-identical output matters; an explicit configuration reduces, but cannot remove, version-to-version formatting differences.

Language: sections extend the default section for a specific language:

---
BasedOnStyle: LLVM
IndentWidth: 4
---
Language: Cpp
PointerAlignment: Left

For standard input or an extensionless file, pass --assume-filename=example.cc so language detection and repository discovery match the target source.

Invoking the Formatter #

Use the committed policy in every invocation:

# Rewrite complete files selected by the build or a file list.
clang-format --style=file -i src/widget.cc include/widget.h

# Rewrite only changed lines. The offsets are byte offsets in this invocation.
clang-format --style=file -i --offset=120 --length=400 src/widget.cc

# Check a CI file set without modifying it.
clang-format --style=file --dry-run --Werror src/widget.cc include/widget.h

Editors should invoke clang-format with --style=file on save or on an explicit format command. CI should run the same executable version and check only tracked files relevant to the project; shell globs omit files in nested directories and can vary by shell. A reviewable CI script can obtain the file list from Git or the build system and fail when formatting would produce a diff.

--style=file:/absolute/path/to/.clang-format selects one known file and avoids parent discovery. Use it for generated tooling or a monorepo policy that must not vary by subdirectory.

Separating Layout from Review #

Formatting is deterministic for a particular formatter version, source, configuration, and requested ranges. Run it before creating a patch, and keep an adoption reformat separate from functional changes. Because reviewers can then ignore layout churn, semantic diffs remain readable.

Avoid treating formatting output as a compiler or a security check. clang-format can sort includes and rewrite line breaks, but it neither resolves includes nor validates compilation. Protect exceptional layout with the documented clang-format off and clang-format on comments only when the generated or tabular form cannot be represented by policy; explain the exception beside the directive.