Terraform HCL Formatter

Terraform Formatting: Why and How

Infrastructure as Code repositories accumulate noise, inconsistent indentation, varied alignment styles, mixed quote conventions, stray whitespace, because many engineers touch the files over years. terraform fmt exists to make formatting boring: every file looks the same, every reviewer focuses on what changed semantically (not what changed cosmetically), and CI gates merge-ability on cleanliness. This tool replicates the format rules in the browser so you don't need a local Terraform install just to clean up a file.

HCL: A 5-Minute Tour

HashiCorp Configuration Language has three primary constructs:

Blocks

A block has:

• Type (resource).
• Labels ("aws_instance" "web", number depends on block type).
• Body in { ... } containing attributes and nested blocks.

Attributes

Identifier, equals sign, expression.

Expressions

Literals, variable refs, attribute access, function calls, interpolation ("${expr}").

Comments

What `terraform fmt` Changes

1. Indentation

2 spaces per level. Tabs replaced with spaces.

2. Alignment of consecutive `=` signs

Within a block, single-line assignments get their = aligned:

Alignment resets at blank lines or nested blocks.

3. Block spacing

One blank line between top-level blocks; no leading/trailing whitespace.

4. Multi-line lists/maps

Trailing commas added; consistent indentation.

5. Quoting

Strings always double-quoted. Heredocs preserved.

6. Trailing whitespace

Removed from end of lines.

What `terraform fmt` Does NOT Change

• Block order, fmt preserves the order you wrote.
• Comments, preserved with adjacent lines.
• Logical structure, modules, resources, expressions identical.
• Identifier choices, variable names, resource names left alone.
• Validation, fmt is syntactic only; use terraform validate for semantic checks.

Integration

Editor

Most editors auto-format on save with an HCL extension:

• VS Code: HashiCorp Terraform extension.
• JetBrains IDEs: HCL plugin.
• Vim/Neovim: vim-terraform plugin or LSP-based formatting.
• Sublime: Terraform package.

Set "editor.formatOnSave": true for the language.

Pre-commit hook

Using the pre-commit framework:

Catches anything missed by editor; runs locally before commit.

CI gate

GitHub Actions / GitLab CI / Jenkins:

Fails the build if any file would be reformatted. Safety net for cases where someone bypasses the editor / hook.

Common Patterns

Module structure

Variables

Outputs

Formatting Conventions Beyond `fmt`

terraform fmt handles whitespace. Other conventions you'll see in style guides:

File organization

• main.tf, primary resources.
• variables.tf, input variables.
• outputs.tf, output values.
• versions.tf, provider/Terraform version constraints.
• locals.tf, locals block.
• data.tf, data sources.

Naming

• Resources: snake_case, descriptive. aws_instance.web_server (not webServer).
• Variables: snake_case. instance_count (not instanceCount or InstanceCount).
• Don't repeat the type: resource "aws_instance" "web" not "aws_instance" "web_instance".

Tags

Always include:

For shared baseline tags, define once in locals or a variable, merge per-resource.

Modules

Pinned versions for production:

Never use source = "git::https://..." without a tag/SHA, supply-chain risk.

Edge Cases the Formatter Handles

Heredoc strings

Preserved as-is; internal whitespace not realigned.

Multi-line expressions

Re-indented per block depth.

Comments adjacent to attributes

Inline comments preserved with their line; standalone comments stay where they were.

Tools Beyond `fmt`

• terraform validate, semantic check (references, types).
• terraform plan, show changes vs current state.
• tflint, opinionated linter (deprecated attributes, type mismatches, best practices).
• tfsec / checkov / trivy, security scanners.
• infracost, cost estimation from Terraform plan.
• terraform-docs, generate README from variables.tf / outputs.tf.
• OpenTofu, fork of Terraform (post-license-change in 2023); tofu fmt is equivalent.

fmt is the floor of code quality; the rest provide ceilings.

Migration: tabs to spaces, mixed indentation

For repos that predate fmt or were created by various contributors:

1. Run terraform fmt -recursive on the whole repo.
2. Commit as a single "fmt all files" PR, review the diff, mostly whitespace.
3. Add CI check + pre-commit hook so it stays clean.

Don't intermix formatting changes with semantic changes in the same PR, reviewers can't tell what actually changed.

Privacy

The formatter parses HCL with a JavaScript HCL parser running in your browser, applies alignment/indentation rules, and emits the formatted string. Open DevTools Network during use: zero outbound requests. Terraform code is among the most sensitive content in any infrastructure repo, it encodes cloud account IDs, VPC ranges, IAM policies, S3 bucket names, secret-management paths, deployment topology. Pasting into an online formatter that uploads would disclose infrastructure architecture. This tool runs locally; what you paste stays in the tab.