tfsort

README

tfsort

tfsort is a command-line utility designed for meticulous engineers who prefer to keep their Terraform variable, output, locals and terraform blocks sorted alphabetically. It also corrects spacing issues between these blocks and removes leading or trailing newlines in the processed files. tfsort can read from files or stdin, write to files or stdout, and process directories recursively.

Contents

• Demo
• Key Features
• Supported File Types
• Installation
  • Homebrew
  • Nix
  • Chocolatey (Windows)
  • Using go install
  • Binary Release
  • From Source
• Usage
  • Command Synopsis
  • Arguments
  • Flags
• Examples
• Contributing
• Code of Conduct
• Author
• License

Demo

Key Features

• Alphabetical Sorting: Sorts variable, output, locals and terraform blocks within your HCL files.
• Flexible Input/Output:
  • Read from a specific file or standard input (stdin).
  • Overwrite the input file, write to a new file, or print to standard output (stdout).
• Recursive Processing: Sort files in an entire directory and its subdirectories.
  • Intelligently skips common version control (.git) and Terraform utility directories (.terraform, .terragrunt-cache).
• Dry Run Mode: Preview changes without modifying any files.
• Code Formatting:
  • Corrects spacing between sorted blocks.
  • Removes unnecessary leading or trailing newlines from the file.

Supported File Types

tfsort processes files with the following extensions:

• .tf
• .hcl
• .tofu

Installation

Homebrew

To install tfsort using Homebrew:

1. Add the tap:

   brew tap alexnabokikh/tfsort
   

2. Install tfsort:

   brew install tfsort
   

Nix

nix-env -iA nixpkgs.tfsort

Chocolatey (Windows)

To install tfsort using Chocolatey:

choco install tfsort

Using go install

If you have Go installed and configured, you can install tfsort directly using go install:

go install github.com/AlexNabokikh/tfsort@latest

This command will download the source code, compile it, and install the tfsort binary into your $GOPATH/bin or $GOBIN directory (make sure this directory is in your system's PATH).

Binary Release

Download the latest binary release for your operating system from the Releases Page.

From Source

Alternatively, build tfsort from source:

1. Clone the repository:

   git clone https://github.com/AlexNabokikh/tfsort.git
   cd tfsort
   

2. Build the binary:

   go build .
   

   This will create a tfsort executable in the current directory.

Usage

Command Synopsis

tfsort [file_or_directory|-] [flags]

Arguments

• file_or_directory (optional):
  • Path to a single Terraform/HCL file (e.g., variables.tf).
  • Path to a directory to process recursively (requires the -r flag).
• - (optional):
  • Instructs tfsort to read input from stdin.
• If no file/directory argument is provided and stdin is detected as a pipe (e.g., cat file.tf | tfsort), tfsort will read from stdin.
• If no arguments are provided and stdin is not a pipe, tfsort will show the help message.

Flags

• -o, --out <path>:
  • Specifies the path to the output file.
  • If the input is a file and -o is not provided, the input file is overwritten.
  • If the input is stdin and -o is not provided, the output is sent to stdout.
  • This flag cannot be used with -r, --recursive.
• -d, --dry-run:
  • Previews the changes by printing the sorted content to stdout.
  • No files will be modified when this flag is used.
• -r, --recursive:
  • Recursively sorts supported files in the specified directory.
  • Files are modified in-place unless -d, --dry-run is also specified.
  • If -r is used, a directory path must be provided as an argument.
  • Cannot be used with stdin input (-) or the -o, --out flag.
• -h, --help:
  • Displays a comprehensive help message, listing available commands, arguments, and flags with their descriptions.
• -v, --version:
  • Displays the installed version of the tfsort application, typically including the version number, commit hash, and build date if available.

Examples

1. Sort a single file in-place: (Sorts variable, output, locals and terraform blocks in my_variables.tf and overwrites the file)

   tfsort my_variables.tf
   

2. Sort a single file and write to a new file:

   tfsort my_variables.tf -o sorted_variables.tf
   

3. Preview changes for a single file (dry run): (Prints the sorted content to the console without modifying my_variables.tf)

   tfsort my_variables.tf -d
   

4. Sort content from stdin and print to stdout:

   cat my_config.tf | tfsort -
   

   Or, if tfsort is part of a pipeline and no file argument is given:

   cat my_config.tf | tfsort
   

5. Sort content from stdin and write to a file:

   cat my_config.tf | tfsort - -o sorted_from_stdin.tf
   

6. Recursively sort files in a directory (in-place): (Sorts all .tf, .hcl, .tofu files in my_terraform_project/ and its subdirectories, modifying them in-place. Skips .git, .terraform, .terragrunt-cache.)

   tfsort -r ./my_terraform_project/
   

7. Recursively sort files in a directory (dry run): (Prints what would be changed for each file to the console without modifying them.)

   tfsort -r ./my_terraform_project/ -d
   

Contributing

Contributions are welcome! Please read the CONTRIBUTING.md file for guidelines on how to contribute to this project, including code contributions, bug reports, and feature suggestions.

Code of Conduct

This project adheres to the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code. Please read the CODE_OF_CONDUCT.md file for details.

Author

This project was created by Alexander Nabokikh.

License

This software is available under the following licenses:

• Apache 2.0