title: Formatter usage

Using the formatter

Mago's formatter is designed to be simple to run. You can format your entire project, specific directories, or even code piped from stdin.

Formatting your project

To format all the source files defined in your mago.toml configuration, simply run:

mago fmt

This command will find all relevant files and overwrite them in place with the formatted version.

Checking for formatting issues

In a continuous integration environment, you'll want to check if files are formatted correctly without actually changing them. The --check flag is perfect for this.

mago fmt --check

This command will exit with a success code (0) if all files are correctly formatted, and a failure code (1) if any files would be changed. No output is printed on success, making it ideal for scripts.

Previewing changes

If you want to see what changes the formatter would make without modifying any files, use the --dry-run flag.

mago fmt --dry-run

This will print a diff of all proposed changes to your console.

Formatting specific directories or files

You can also format specific files or directories by passing them as arguments:

# Format a specific file
mago fmt src/Service.php

# Format a specific directory
mago fmt src/

Formatting from stdin

You can format code directly from standard input (stdin). This is useful for integrating with other tools or scripts.

cat src/Service.php | mago fmt --stdin-input

This will read the code from src/Service.php, format it, and print the formatted code to standard output.

Formatting staged files (pre-commit hooks)

The --staged flag is designed for git pre-commit hooks. It formats only the files currently staged for commit and automatically re-stages them:

mago fmt --staged

This is ideal for ensuring all committed code is properly formatted without affecting unstaged changes.

For a complete guide on setting up pre-commit hooks, see the pre-commit hooks recipe.

For more details on the available command-line options, see the Command Reference.