Using Terraform fmt Command to Format Your Terraform Code

In this post, we will look at the terraform fmt command, first explaining what it does and when to run it, looking at the operation it performs, and showing some useful examples using the available options.

The terraform fmt command is used to format your configuration files into a canonical format and style. This command applies a subset of the Terraform language style conventions, along with other minor adjustments for readability.

As a best practice, terraform fmt should always be run on your configuration files, so formatting standards and language style conventions are applied across your configuration in a uniform manner. This helps code readability and ensures all configuration files are formatted the same, no matter which team member is writing the file. Consistency can help your team understand the code more quickly and easily, making the use of terraform fmt very important.

Each version of Terraform may introduce changes to the way the terraform fmt command actually adjusts your configuration files, so it should be run each time a different version of Terraform is used. It should be noted that Hashicorp acknowledges that formatting decisions are always subjective, and the style they have chosen might not be agreed upon by everyone, however, having a standard and providing a command to automatically format the configuration consistently achieves the primary goal.

Inserting a step into your CI/CD pipeline or running automated checks to ensure terraform fmt has been run on the configuration files is a good idea. One way of achieving this is to use the -check option, if there are changes required, it will return a non-zero code (1 for error); if there are no changes, it will return a zero code and should be allowed to pass to the next stage.

If a non-zero error code is returned, the -diff option can be used to display the diffs of the formatting changes that the fmt command will make. If there are no diffs, then the pipeline stage should be allowed to pass as complete, if there are diffs, then the pipeline should fail, and the writer of the configuration file should be notified that they need to run the terraform fmt command on their configuration files before committing to source control.

Note: New versions of Terraform are placed under the BUSL license, but everything created before version 1.5.x stays open-source. OpenTofu is an open-source version of Terraform that expands on Terraform’s existing concepts and offerings. It is a viable alternative to HashiCorp’s Terraform, being forked from Terraform version 1.5.6.

Usage: terraform fmt [options] [TARGET]

The target can be a directory or a single filename. You can also specify a - for the target, which then takes input from STDIN.

terraform fmt has the following optional flags:

-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

-check – Check if the input is formatted. The exit status will be 0 if all input is properly formatted and non-zero otherwise.

-recursive – Also, process files in subdirectories. By default, only the given directory (or current directory) is processed.

To show how these options work in practice, let’s look at some examples.

I have a main.tf file that looks like this — note the bad formatting!

After I run terraform fmt my file looks like this:

• The indentation of the required_providers block is fixed and instantly become easier to read.
• Terraform lists the main.tf file after my terraform fmtcommand to show that it was changed. To stop this from being listed, the -list=false option can be used. Alternatively, the -write=false option will list the files to be changed but not actually write the changes.
• The extra spaces in the backend block and in the ad_group module call are not removed. That has to be done manually if required.

To use the -diff option, Terraform references the diff external command. If you don’t have diff installed already (likely on a Windows machine), you will see the following error:

Note that even though the error is generated, the file formatting is still corrected.

To resolve this error on a windows machine, you can install GNU diffutils using chocolatey. Chocolately is a popular package manager for Windows. Once installed, you can simply run the following command in an elevated command prompt:

Once installed, restart your terminal, and the diff will be successfully generated:

This can be a useful option when running in automation to track the changes written to the file.

Moving on to the -check option, this will show one exit code (error) and list the files to be changed if there are changes to be made. If there are no changes, a zero exit code (pass) will be returned, and no files will be listed. As mentioned previously, this can be useful in automation.

Lastly, the -recursive option is useful to make sure all the Terraform configuration files in the directory structure are formatted. By default, terraform fmt only formats files in the current directory, not the subdirectories. Usually, project configuration files will be separated into logical folders or contain submodules, which will also need to be formatted correctly.

I hope with this blog post, you learned how to format your Terraform code with the Terraform fmt command.

If you’re interested in finding out how to use Spacelift to manage and automate your Terraform deployments check out our Terraform documentation and sign up for a free trial.

Cheers!