tgsort

tgsort sorts blocks and attributes in Terragrunt HCL files — like gofmt, but for Terragrunt configuration. It rewrites files in-place so your terragrunt.hcl always has a consistent, reviewable layout regardless of who wrote it.

Installation

Homebrew (macOS and Linux)

brew tap salemgolemugoo/tap
brew install tgsort

Go install

go install github.com/salemgolemugoo/tgsort@latest

Binary

Download a pre-built binary for your platform from the Releases page.

Usage

tgsort [file_or_directory|-] [flags]

Flags:
  -d, --dry-run     Print a unified diff without modifying files; exits 1 if any file would change
  -r, --recursive   Recurse into subdirectories when a directory is given
  -v, --version     Print version and exit

Note: .hcl.json files are not supported and will produce an error.

Examples

# Sort all .hcl files in the current directory
tgsort

# Sort a single file
tgsort terragrunt.hcl

# Sort an entire module tree recursively
tgsort --recursive ./modules

# Preview changes without writing them
tgsort --dry-run

# Read from stdin, write sorted output to stdout
cat terragrunt.hcl | tgsort -

# CI gate — fail if any files are unsorted
tgsort --dry-run --recursive .

Configuration

Place a .tgsort file in the directory where you run tgsort. It is optional — all fields have defaults and an absent file is silently ignored. A malformed file is a fatal error.

# .tgsort
block_order        = ["terraform", "remote_state", "include", "locals", "generate", "dependency", "inputs"]
sort_attributes_in = ["inputs"]

Field	Default	Description
block_order	["terraform", "remote_state", "include", "locals", "generate", "dependency", "inputs"]	Block types sorted in this order; types not listed sort alphabetically after
sort_attributes_in	["inputs"]	Attribute keys inside these block bodies or attribute map literals are also sorted

How it works

tgsort parses HCL with hclsyntax to identify top-level block and attribute positions, then reorders them using a stable sort — preserving exact whitespace and inline formatting. Comments immediately preceding a block travel with that block during reordering. Single-line object expressions (e.g. inputs = { key = "value" }) are left unsorted.

Contributing

# Install pre-commit hooks
pre-commit install

# Unit tests
go test ./...

# Integration tests (compiles the binary and runs golden-file fixtures)
go test -tags integration ./...

# Race detector
go test -race ./...

Commits must follow Conventional Commits — enforced by the commit-msg pre-commit hook.