How to use the command 'ruff format' (with examples)

The ruff format command is a specialized tool designed for Python developers who seek to maintain clean, well-structured code. It provides a fast and efficient way to format Python code uniformly across projects. This command can handle multiple files and directories, ensuring that code style remains consistent, whether you are working alone or in a collaborative setting with a team. The format operation helps enforce coding standards, reduces the likelihood of stylistic errors, and enhances code readability.

Use case 1: Format given files or directories in-place

Code:

ruff format path/to/file_or_directory1 path/to/file_or_directory2 ...

Motivation:

Developers often work on extensive projects with multiple Python scripts and directories. Ensuring that all these files adhere to a specific formatting style can be time-consuming if done manually. This use case is advantageous to automatically sanitize the Python files’ format within one or more specified directories or particular files themselves, ensuring consistency across the board, which is crucial for collaborative coding environments. This approach not only saves time but also focuses efforts on more critical development tasks rather than format corrections.

Explanation:

In this example, you provide specific paths to files and directories that you wish to format. The paths can be absolute or relative, depending on where you execute the command. Using this command, ruff will format the files in their current locations (“in-place”), meaning the source code in these files will be directly overwritten with the newly formatted version. This ensures that you don’t have to worry about copying modified files or handling temporary files — the changes are immediately applied.

Example output:

Formatted: path/to/file_or_directory1/example_script.py
Formatted: path/to/file_or_directory2/sample_code.py
2 files formatted in total.

Use case 2: Print which files would have been modified and return a non-zero exit code if there are files to reformat, and zero otherwise

Code:

ruff format --check

Motivation:

This use case is highly beneficial when integrating the command into automated workflows such as Continuous Integration (CI) pipelines or pre-commit hooks. By using --check, you can ensure that any Python files that deviate from the desired coding style are identified before actual changes occur or critical processes, such as deployments, proceed. It assists developers by flagging files needing reformatting, allowing them to address styling issues proactively.

Explanation:

The --check flag instructs ruff to assess the format of every file in the current working directory without making any modifications. The command will output a list of files that would undergo changes if formatted. This feature is crucial in control situations where you need to confirm which files are out of format compliance. Importantly, the command will return a non-zero exit code if any files require formatting, which is informative for scripts and automation tools that need to take action based on code formatting status.

Example output:

Would reformat: path/to/file/example_script.py
Would reformat: path/to/another_file/sample_code.py
2 files would be reformatted in total.

Use case 3: Print what changes would be made without modifying the files

Code:

ruff format --diff

Motivation:

In situations where developers are hesitant to apply automated formatting changes directly or want to verify changes before they are applied, using --diff provides a safe preview. This option is especially useful for reviewing changes in a collaborative team environment, allowing teams to check intended modifications before approval and implementation. It gives developers a detailed look at potential changes, fostering better collaboration and understanding among team members regarding code format and style decisions.

Explanation:

This command utilizes the --diff flag, which generates and displays a diff for any Python file that would have been reformatted. This is a non-destructive operation, meaning your original files remain unchanged. Instead, it visually presents the differences in a format similar to that produced by tools like git diff. This insight is invaluable during code reviews, offering a clear picture of what the formatting changes entail and whether they align with desired coding standards or guidelines.

Example output:

--- path/to/file.example_script.py
+++ path/to/file.example_script.py
@@ -1,6 +1,6 @@
 def example_function():
-    print( "Hello, world!" )
+    print("Hello, world!")
  
 if __name__ == "__main__":
-  example_function()
+    example_function()

Conclusion:

The ruff format command is a powerful asset for Python developers and teams striving for a consistent and efficient codebase. Each of the outlined use cases demonstrates its flexibility and utility across different coding scenarios, from direct in-place formatting to assistance in automated workflows and careful review stages. By integrating this tool into regular development practices, teams can significantly enhance code readability, maintainability, and collaboration efficiency.