clang-format

Format a file and print the result to stdout

$ clang-format [path/to/file]

$ clang-format -i [path/to/file]

$ clang-format --style [LLVM|GNU|Google|Chromium|Microsoft|Mozilla|WebKit] [path/to/file]

$ clang-format --style=file [path/to/file]

$ clang-format --style [LLVM|GNU|Google|Chromium|Microsoft|Mozilla|WebKit] --dump-config > [.clang-format]

clang-format [options] [files...]

Common usage examples:
clang-format -i file.cpp
clang-format --style=Google mycode.h
cat input.js | clang-format --assume-filename=file.js > formatted.js

--style=<string>
    Specifies the formatting style. Can be a predefined name (e.g., LLVM, Google, Chromium, Microsoft, Mozilla, WebKit), a path to a configuration file, a YAML configuration string, or file to discover the style from a .clang-format file.

-i, --in-place
    Format files in-place. This option overwrites the original input files with the formatted content.

--assume-filename=<path>
    When formatting standard input, assume the content comes from this file. This helps clang-format locate the correct style configuration file and apply language-specific rules.

--dump-config
    Prints the current style configuration to standard output, typically derived from the closest .clang-format file or the default style.

--dry-run
    Don't apply changes; instead, print the names of files that would be reformatted. Useful for checking which files are out of compliance.

--sort-includes
    Sorts include blocks lexicographically, often organizing them into groups. This can be controlled further by style options.

--version
    Display the version of clang-format and exit.

clang-format is an integral part of the LLVM project, designed to automatically format source code in various languages, including C, C++, Objective-C, C#, Java, JavaScript, TypeScript, and Protocol Buffers.

Its primary goal is to ensure consistent coding styles across a project, enhancing code readability and maintainability. It achieves this by applying a set of predefined or custom rules, often specified in a .clang-format or _clang-format YAML configuration file located within the project directory or user's home. This allows for fine-grained control over indentation, line breaks, brace styles, and more.

clang-format supports several popular built-in styles (e.g., LLVM, Google, Chromium, Microsoft) and can also infer a style from existing code. It can format files in-place, print changes to standard output, or generate diffs, making it suitable for integration into build systems, editor plugins, and version control pre-commit hooks. Its automation significantly reduces bikeshedding over code style, allowing developers to focus on functionality.

While highly effective, clang-format relies heavily on its configuration.
Inconsistent or poorly defined .clang-format files can lead to unexpected reformatting.
It focuses solely on code style, not semantic correctness or bug detection.
For large-scale legacy codebases, an initial formatting pass might result in significant changes, potentially complicating git history if not managed carefully.

When formatting a file, clang-format intelligently searches for its configuration file (.clang-format or _clang-format). It starts in the directory of the input file and traverses up the directory tree until it finds a configuration file or reaches the root of the file system. This mechanism ensures that project-specific or even sub-directory-specific styles can be applied automatically.

One of clang-format's strengths is its seamless integration with various text editors and Integrated Development Environments (IDEs). Plugins are available for popular tools like VS Code, Vim, Emacs, Sublime Text, and more, allowing developers to format code on-save, on-demand, or as part of a pre-commit hook. This immediate feedback helps maintain code style consistency throughout the development workflow.

clang-format was developed as a sub-project of Clang, which is part of the broader LLVM compiler infrastructure project. It first appeared in the LLVM ecosystem around 2012-2013, with early versions integrated into Clang 3.3/3.4. Its creation aimed to provide an official, robust, and extensible code formatter tightly integrated with the Clang parser. This allowed it to understand the abstract syntax tree (AST) of the code, enabling more intelligent and accurate formatting than regex-based tools. Its YAML-based configuration system quickly led to widespread adoption in C++ and other language communities due to its flexibility and ease of sharing style rules.

astyle(1), uncrustify(1), indent(1), git(1)