uncrustify

Format a single file

$ uncrustify -f [path/to/file.cpp] -o [path/to/output.cpp]

$ find . -name "*.cpp" | uncrustify -F - --replace

$ find . -name "*.cpp" | uncrustify -F - --no-backup

$ uncrustify -c [path/to/uncrustify.cfg] -f [path/to/file.cpp]

$ uncrustify --set [option]=[value]

$ uncrustify --update-config -o [path/to/new.cfg]

uncrustify [options] [files...]
uncrustify -c <config_file> [options] [files...]

-c <file>
    Specifies the path to the configuration file. This is crucial for defining formatting rules.

--check
    Checks if files are uncrustified without modifying them. Exits with a non-zero status if any file needs reformatting.

-F <file>
    Reads a list of files to process from the specified <file>, one file path per line.

-l <language>
    Forces the input language. Supported values include C, CPP, CS, OC, D, JAVA, PAWN, V, etc.

-o <file>
    Specifies the output file. If not provided, output goes to stdout. Not applicable with --replace.

--replace
    Replaces the input file(s) in place with the formatted content.

--show-config
    Prints the active configuration to standard output, useful for debugging.

--set-config <key>=<value>
    Overrides a configuration option directly from the command line. Can be used multiple times.

--version
    Displays the program version information and exits.

--help
    Shows a brief help message with common command-line options.

Uncrustify is a powerful and highly configurable C, C++, C#, Objective-C, D, Java, Pawn, and VALA source code beautifier. It automatically adjusts indentation, spacing, and line breaks to conform to a specific coding style. Unlike simpler formatters, Uncrustify offers thousands of configuration options, allowing users to define intricate rules for virtually every aspect of code layout. This makes it an invaluable tool for enforcing consistent coding standards across large projects and development teams, improving code readability and maintainability. It operates by reading a configuration file that dictates the desired formatting rules, then applies these rules to source code files.

Uncrustify's power comes with a steep learning curve due to its extensive configuration options. Generating and fine-tuning a suitable configuration file (uncrustify.cfg) can be time-consuming. Incorrect configurations may inadvertently alter code logic or introduce undesirable formatting. Always use version control and test changes before applying them widely.

The core of Uncrustify's functionality lies in its configuration file, typically named uncrustify.cfg. This file contains thousands of boolean, integer, and string options that dictate how the code should be formatted. Users often start by generating a default configuration (e.g., using uncrustify --show-config > uncrustify.cfg) and then incrementally customize it to match their specific coding standards.

A typical workflow involves:
1. Create or obtain a configuration file: uncrustify --show-config > my_style.cfg
2. Edit my_style.cfg to define desired rules.
3. Format files in place: uncrustify -c my_style.cfg --replace *.cpp
4. To check compliance in CI/CD: uncrustify -c my_style.cfg --check *.cpp

Uncrustify was initiated by Ben Gardner in 2006 as a robust code beautifier. It quickly gained traction among developers due to its highly customizable nature, offering far more control over coding style than many contemporary tools. It remains an actively maintained open-source project, with continuous improvements and additions of new configuration options and language support.

astyle(1), clang-format(1), indent(1)