How to use the command 'uncrustify' (with examples)

Uncrustify is a source code beautifier that helps in maintaining consistent code formatting across different programming languages like C, C++, C#, D, Java, and Pawn. It plays a crucial role in enhancing code readability and maintaining a standard coding style, making collaboration among developers much smoother. By giving developers tools to automate code formatting, Uncrustify helps in reducing manual effort and potential errors in formatting.

Format a single file

Code:

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

Motivation: Sometimes, you may have a single source code file that needs to be restructured to conform to your preferred style guide. Whether for readability improvements or to match a team standard, reformatting a single file can help in increasing the maintainability of the code.

Explanation:

• -f path/to/file.cpp: Specifies the file to be formatted. The -f flag stands for ‘file’, indicating the input source code file you want to format.
• -o path/to/output.cpp: This specifies the output location where the formatted file will be saved. The -o flag stands for ‘output’.

Example Output: Once executed, this command formats the specified C++ file, producing a neatly aligned and styled source code at the specified output path.

Read filenames from stdin, and take backups before writing output back to the original filepaths

Code:

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

Motivation: When managing a large project with numerous source code files, it becomes essential to format all C++ files in one go. This command is especially useful for batch processing where multiple files require the same formatting treatment, ensuring uniformity across the board.

Explanation:

• find . -name "*.cpp": This finds all files with the .cpp extension, beginning from the current directory and traversing all its subdirectories.
• |: A pipe that connects the output of the find command to the input of the uncrustify command.
• uncrustify -F -: The -F flag denotes reading from a list of filenames provided by stdin (which is specified by -).
• --replace: This argument tells Uncrustify to overwrite the original files with the formatted output. It also creates backups of the original files by default.

Example Output: Executing this command results in all located C++ files being formatted, with backups of the unformatted files saved in the same directories.

Don’t make backups (useful if files are under version control)

Code:

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

Motivation: When you are working with files under version control systems like Git, making backups is redundant because version control systems inherently keep track of file modifications. Thus, this option eliminates unnecessary backup clutter.

Explanation:

• --no-backup: A flag to suppress the automatic creation of backup files while still applying the formatting changes directly to the original files.

Example Output: After running this command, all .cpp files are formatted without creating any backup files, reducing clutter while maintaining a clean history in your version control system.

Use a custom configuration file and write the result to stdout

Code:

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

Motivation: Different projects may have unique coding styles requiring a tailored configuration. By specifying a custom configuration file, developers can ensure that their code adheres to specific guidelines, without altering global or default settings.

Explanation:

• -c path/to/uncrustify.cfg: This flag is used to provide custom configuration settings stored in the specified file. It overrides the default settings, allowing for a personalized formatting standard.
• -f path/to/file.cpp: Points to the file that needs formatting.

Example Output: The command prints the formatted version of the specified file to the standard output, allowing users to immediately view changes or redirect it as needed.

Explicitly set a configuration variable’s value

Code:

uncrustify --set option=value

Motivation: When specific formatting tweaks are needed on-the-fly, setting configuration parameters directly in the command line can streamline the process. This flexibility allows precise adjustments without modifying the entire configuration file.

Explanation:

• --set option=value: This argument allows setting a specific configuration parameter instantly, which alters the formatting behavior according to the newly defined options and values.

Example Output: This outputs a formatted code that reflects the change in the specific configuration parameter, providing immediate feedback on formatting adjustments.

Generate a new configuration file

Code:

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

Motivation: Developers starting with a new project often need a baseline configuration to ensure their code meets a proper stylistic standard at the outset. Generating a new configuration file helps kickstart this process by providing a template configuration.

Explanation:

• --update-config: This argument prompts Uncrustify to generate a new configuration based on the current settings.
• -o path/to/new.cfg: Writes the generated configuration to the specified file path, making it easy to review, modify, and distribute.

Example Output: A new configuration file is created at the provided output path, which can then be used to format future source files consistently across the project or multiple projects.

Conclusion:

Through these examples, Uncrustify proves itself as a robust tool for source code formatting, with versatile options catering to various developer needs, from single-file formatting to batch processing and configuration management. These use cases demonstrate how Uncrustify can effectively streamline the process of code standardization and maintainability across different programming projects.