---
description: >-
  The tofu fmt command rewrites configuration files to a canonical format
  and style.
---

# Command: fmt

The `tofu fmt` command is used to rewrite OpenTofu configuration files
to a canonical format and style. This command applies a subset of
the [OpenTofu language style conventions](../../language/syntax/style.mdx),
along with other minor adjustments for readability.

Other OpenTofu commands that generate OpenTofu configuration will produce
configuration files that conform to the style imposed by `tofu fmt`, so
using this style in your own files will ensure consistency.

The canonical format may change in minor ways between OpenTofu versions, so
after upgrading OpenTofu we recommend to proactively run `tofu fmt`
on your modules along with any other changes you are making to adopt the new
version.

We don't consider new formatting rules in `tofu fmt` to be a breaking
change in new versions of OpenTofu, but we do aim to minimize changes for
configurations that are already following the style examples shown in the
OpenTofu documentation. When adding new formatting rules, they will usually
aim to apply more of the rules already shown in the configuration examples
in the documentation, and so we recommend following the documented style even
for decisions that `tofu fmt` doesn't yet apply automatically.

Formatting decisions are always subjective and so you might disagree with the
decisions that `tofu fmt` makes. This command is intentionally opinionated
and has no customization options because its primary goal is to encourage
consistency of style between different OpenTofu codebases, even though the
chosen style can never be everyone's favorite.

We recommend that you follow the style conventions applied by `tofu fmt`
when writing OpenTofu modules, but if you find the results particularly
objectionable then you may choose not to use this command, and possibly choose
to use a third-party formatting tool instead. If you choose to use a
third-party tool then you should also run it on files that are generated
automatically by OpenTofu, to get consistency between your hand-written files
and the generated files.

## Usage

Usage: `tofu fmt [options] [target...]`

By default, `fmt` scans the current directory for configuration files. If you
provide a directory for the `target` argument, then `fmt` will scan that
directory instead (see [Directory Scanning Behavior](#directory-scanning-behavior)).
If you provide a file, then `fmt` will process just that file. If you provide
a single dash (`-`), then `fmt` will read from standard input (STDIN).

The command-line flags are all optional. The following flags are available:

* `-list=false` - Don't list the files containing formatting inconsistencies.
* `-write=false` - Don't overwrite the input files. (This is implied by `-check` or when the input is STDIN.)
* `-diff` - Display diffs of formatting changes.
  * When using this flag, ensure that `diff` tool is installed. This is used internally for providing a better user experience.
* `-check` - Check if the input is formatted. Exit status will be 0 if all input is properly formatted. If not, exit status will be non-zero and the command will output a list of filenames whose files are not properly formatted.
* `-recursive` - Also process files in subdirectories. By default, only the given directory (or current directory) is processed.

## Directory Scanning Behavior

When `tofu fmt` scans a directory, it applies the following rules to decide
which files to process:

- **Exclusion rule**: Any file whose name starts with `.` or `~`, or whose name
  both starts and ends with `#`, is skipped. These patterns typically indicate
  temporary files created by text editors or other tools, and `tofu fmt` skips
  them to avoid interfering with that software.

- **Inclusion rule**: After applying the exclusion rule, only files with the
  following extensions are processed:
  `.tf`, `.tofu`, `.tfvars`, `.tftest.hcl`, `.tofutest.hcl`

For example, a file named `.auto.tfvars` would be excluded because its name
starts with `.`, even though it has the `.tfvars` suffix.
