uncrustify is a source code formatter for languages like C, C++, C#, D, Java, and Pawn. It helps in automatically formatting code according to a specific coding style or configuration file. This article provides examples of various use cases for the uncrustify command.

Use case 1: Format a single file

Code:

uncrustify -f path/to/file.cpp -o path/to/output.cpp

Motivation: Formatting a single file using uncrustify can be helpful when wanting to ensure consistent formatting throughout the codebase. By specifying the input file using the -f flag and the output file using the -o flag, uncrustify will format the code and write the formatted result to the output file.

Explanation:

• -f path/to/file.cpp: Specifies the input file path.
• -o path/to/output.cpp: Specifies the output file path.

Example Output: The code in path/to/file.cpp will be formatted according to the configured coding style, and the formatted code will be written to path/to/output.cpp.

Use case 2: Read filenames from stdin and take backups before writing output back to the original filepaths

Code:

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

Motivation: When working with a large codebase, it can be time-consuming to manually format each file. This use case allows using the find command to locate all .cpp files in the current directory and its subdirectories. By piping the file paths to uncrustify, the command formats the code and overwrites the original files while creating backups of the original files.

Explanation:

• find . -name "*.cpp": Finds all .cpp files in the current directory and its subdirectories.
• |: Pipes the resulting file paths to the next command.
• uncrustify -F - --replace: Formats the code using uncrustify, overwrites the original files, and creates backups of the original files.

Example Output: Each .cpp file found by the find command will be formatted, and the original files will be replaced with the formatted code. Backups of the original files will also be created.

Use case 3: Don’t make backups (useful if files are under version control)

Code:

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

Motivation: In some scenarios, such as when files are under version control, it may be unnecessary to create backups while formatting code. This use case allows using uncrustify without generating backups.

Explanation:

• find . -name "*.cpp": Finds all .cpp files in the current directory and its subdirectories.
• |: Pipes the resulting file paths to the next command.
• uncrustify -F - --no-backup: Formats the code using uncrustify, overwrites the original files without creating backups.

Example Output: Each .cpp file found by the find command will be formatted, and the original files will be replaced with the formatted code. No backups of the original files will be created.

Use case 4: Use a custom configuration file and write the result to stdout

Code:

uncrustify -c path/to/uncrustify.cfg -f path/to/file.cpp

Motivation: Sometimes, it is required to use a custom configuration file for code formatting. This use case demonstrates how to specify a custom configuration file for uncrustify and output the formatted code to the standard output (stdout) instead of writing it to a file.

Explanation:

• -c path/to/uncrustify.cfg: Specifies the path to the custom configuration file.
• -f path/to/file.cpp: Specifies the input file path.

Example Output: The code in path/to/file.cpp will be formatted according to the custom configuration file, and the formatted code will be displayed on the console (stdout).

Use case 5: Explicitly set a configuration variable’s value

Code:

uncrustify --set option=value

Motivation: uncrustify allows configuring various formatting options using configuration files. This use case demonstrates how to explicitly set the value of a configuration variable without modifying the configuration file.

Explanation:

• --set option=value: Sets the value of the specified configuration option to the provided value.

Example Output: The specified configuration option will be set to the provided value, which may affect the formatting of the code according to the modified option.

Use case 6: Generate a new configuration file

Code:

uncrustify --update-config -o path/to/new.cfg

Motivation: uncrustify provides the ability to generate a new configuration file based on the currently applied formatting options. This use case demonstrates how to generate a new configuration file from the current configuration.

Explanation:

• --update-config: Generates a new configuration file based on the currently applied formatting options.
• -o path/to/new.cfg: Specifies the output path for the newly generated configuration file.

Example Output: A new configuration file (path/to/new.cfg) will be created with the formatting options reflecting the current configuration.

Conclusion:

The uncrustify command is a powerful tool for automatically formatting source code in various programming languages. It offers flexibility in specifying input files, customizing the formatting using configuration files, and generating new configuration files. By utilizing the different use cases mentioned in this article, developers can ensure consistent code formatting and improve the readability of their codebase.