mirror of
https://github.com/opentffoundation/opentf.git
synced 2026-05-16 16:01:49 -04:00
80 lines
4.0 KiB
Plaintext
80 lines
4.0 KiB
Plaintext
---
|
|
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.
|