Terragrunt hcl fmt 命令完全指南递归格式化 HCL 文件的原理与实战【免费下载链接】terragruntTerragrunt is a flexible orchestration tool that allows Infrastructure as Code written in OpenTofu/Terraform to scale.项目地址: https://gitcode.com/GitHub_Trending/te/terragrunt导读terragrunt hcl fmt是 Terragrunt 提供的 HCL 格式化命令用于递归查找工作目录下所有 HashiCorp Configuration LanguageHCL文件并将其重写为 HashiCorp 官方推荐的规范化格式。本文以 Terragrunt 仓库中该命令的官方文档定义commands 数据文件、flag 定义文件为骨架结合底层实现源码format.go、cli.go展开讲解读完你能够掌握该命令的全部参数、环境变量、退出码约定、CI/CD 集成方式以及其“先语法校验、再并行格式化”的底层实现原理。一、命令概览与定位按照 Terragrunt 官方文档的定义见 hcl/fmt.mdxhcl fmt命令属于configuration类别官方描述为Recursively find HashiCorp Configuration Language (HCL) files and rewrite them into a canonical format.其核心定位有两个关键词Recursively递归默认行为是在工作目录下递归遍历目录树找出所有.hcl文件Canonical format规范化格式重写遵循 HashiCorp 官方语言风格指南即与terraform fmt/tofu fmt完全一致的格式化风格。在命令行中hcl fmt是hcl format子命令的别名。源码 cli.go 中定义const ( CommandName format CommandNameAlias fmt )二、基本用法最简单也是最常用的形式是在 Terragrunt 配置目录下直接执行terragrunt hcl fmt该命令会从当前工作目录opts.WorkingDir出发递归遍历整个目录树对每个.hcl后缀文件执行格式化并写回原文件。从源码 format.go 的遍历逻辑看其默认行为包括仅处理以.hcl结尾的文件strings.HasSuffix(path, .hcl)目录本身会被跳过只收集文件存在一组默认排除目录详见下文第五节。三、命令行参数详解hcl fmt的全部专属参数、环境变量与说明集中定义在 cli.go 与 docs/src/data/flags 目录下的 flag 文档中。下面逐一讲解。1.--check检查模式只检查不修改属性值类型bool环境变量TG_CHECK旧变量TG_HCLFMT_CHECK、TERRAGRUNT_CHECK开启后Terragrunt 只检查 HCL 文件是否已正确格式化不会做任何修改非常适合在 CI/CD 流水线中强制格式一致性所有文件均已正确格式化 → 退出码0存在需要格式化的文件 → 退出码1。terragrunt hcl fmt --check从源码看--check会复用格式化后的内容做字节级比较!bytes.Equal(newContents, contents)一旦发现差异便返回FileNeedsFormattingError见 format.go、errors.go由上层汇总为退出码1。2.--diff打印差异不改写文件属性值类型bool环境变量TG_DIFF旧变量TG_HCLFMT_DIFF、TERRAGRUNT_DIFF开启后Terragrunt 会打印原始版本与格式化版本之间的差异unified diff让你在真正改写之前预览格式化器将要做的改动terragrunt hcl fmt --diff内部实现基于github.com/rogpeppe/go-internal/diff生成 unified diff见 format.godiff 标签统一使用斜杠分隔路径以保证跨平台含 Windows输出一致。3.--exclude-dir排除指定目录属性值类型string可多次指定环境变量TG_EXCLUDE_DIR旧变量TG_HCLFMT_EXCLUDE_DIR、TERRAGRUNT_EXCLUDE_DIR跳过给定目录中的 HCL 文件适合排除vendor、.terragrunt-cache等不需要格式化的目录terragrunt hcl fmt --exclude-dirvendor --exclude-dir.terragrunt-cache注意两点匹配依据是目录的 basenameslices.Contains(opts.HclExclude, basename)见 format.go因此--exclude-dirvendor会排除目录树中任意层级名为vendor的目录该参数与默认排除目录第五节是叠加生效的。4.--file格式化单个文件属性值类型string环境变量TG_FILE旧变量TG_HCLFMT_FILE、TERRAGRUNT_HCLFMT_FILE指定单个 HCL 文件进行格式化替代默认的递归搜索terragrunt hcl fmt --file./environments/prod/terragrunt.hcl相对路径会基于工作目录解析为绝对路径见 format.go。同时指定--file与--stdin会直接报错“both stdin and path flags are specified”。5.--filter基于路径的过滤查询属性值类型list(string)说明对hcl fmt而言只支持路径型过滤表达式--filter在hcl fmt中的行为与其它命令不同它过滤的是单个 HCL 文件而非 unit/stack目录级单位因此只支持基于路径的过滤表达式typeunit、namemy-app这类基于属性的过滤器在此处不可用见 hcl-fmt-filter.mdx。路径匹配支持 glob# 相对路径 glob terragrunt hcl fmt --filter ./envs/prod/** # 格式化特定目录下所有 HCL 文件 terragrunt hcl fmt --filter ./modules/**/*.hcl # 绝对路径 terragrunt hcl fmt --filter /absolute/path/to/envs/dev/apps/*取反!前缀terragrunt hcl fmt --filter !./prod/** terragrunt hcl fmt --filter !./test/**交集 / 精化|运算符# 格式化 prod 目录下的 HCL 文件但排除其中的测试 terragrunt hcl fmt --filter ./prod/** | !./prod/test/** # 格式化所有 HCL 文件排除 test 目录 terragrunt hcl fmt --filter ./**/*.hcl | !./**/test/**并集多个--filterOR 逻辑# 同时格式化 dev 与 staging 两个目录 terragrunt hcl fmt --filter ./dev/** --filter ./staging/**在源码层面收集到全部.hcl文件后会调用filters.EvaluateOnFiles(l, files, workingDir)对文件列表求值见 format.go。更全面的过滤器语法可参考 Filters 功能文档。6.--stdin从标准输入读取并输出到标准输出属性值类型bool环境变量TG_STDIN旧变量TG_HCLFMT_STDIN、TERRAGRUNT_HCLFMT_STDIN从标准输入读取 HCL 内容、格式化后写到标准输出非常适合与编辑器或其他工具集成echo locals { foobar } | terragrunt hcl fmt --stdin与--check/--diff组合时行为不同见 hcl-fmt-stdin.mdx组合--check不打印格式化内容输入需要格式化时退出码为1组合--diff不打印格式化内容打印标签为old/stdin与new/stdin的 unified diff单独使用格式化后的完整内容写入标准输出。对应实现见 format.go其中--check返回FileNeedsFormattingError{Path: stdinPath}。7. 队列与并发参数除上述专属参数外hcl fmt还挂载了一组共享参数见 cli.go--parallelism控制同时格式化的文件数量上限详见第五节队列类参数--queue-exclude-dir、--queue-exclude-external、--queue-excludes-file、--queue-ignore-dag-order、--queue-ignore-errors、--queue-include-dir、--queue-include-external、--queue-include-units-reading、--queue-strict-include用于精细控制遍历范围与错误容忍行为。四、环境变量速查表所有专属 flag 均可通过环境变量设置旧版TG_HCLFMT_*/TERRAGRUNT_*变量仍受支持但已标记废弃flags.WithDeprecatedEnvVars见 cli.go参数新环境变量旧环境变量--checkTG_CHECKTG_HCLFMT_CHECK、TERRAGRUNT_CHECK--diffTG_DIFFTG_HCLFMT_DIFF、TERRAGRUNT_DIFF--exclude-dirTG_EXCLUDE_DIRTG_HCLFMT_EXCLUDE_DIR、TERRAGRUNT_EXCLUDE_DIR--fileTG_FILETG_HCLFMT_FILE、TERRAGRUNT_HCLFMT_FILE--stdinTG_STDINTG_HCLFMT_STDIN、TERRAGRUNT_HCLFMT_STDIN例如在 CI 中可写作TG_CHECKtrue terragrunt hcl fmt五、底层实现原理1. 默认排除目录即使不指定--exclude-dir遍历时也会默认跳过三类目录见 format.govar excludePaths []string{ util.TerragruntCacheDir, // .terragrunt-cache util.DefaultBoilerplateDir, // 模板脚手架相关目录 config.StackDir, // stacks 目录 }匹配发生在vfs.WalkDir回调中命中后直接返回fs.SkipDir剪枝避免无谓下钻见 format.go。2. 格式化内核官方 hcl2 库格式化本身依赖 HashiCorp 官方库github.com/hashicorp/hcl/v2/hclwrite核心只有一行newContents : hclwrite.Format(contents)且格式化前会先用hclparse.NewParser().ParseHCL做一次语法解析checkErrors见 format.go保证“先确认无语法错误、再落盘改写”——解析报错的坏文件不会被盲目改写。只有当新旧内容字节级不一致fileUpdated时才写回文件并保留原文件权限位info.Mode()见 format.go。3. 并发格式化与 worker 上限文件级格式化通过errgroup并行执行。worker 数由formatWorkers决定见 format.go显式指定--parallelism时按用户给定值执行未指定时取min(runtime.GOMAXPROCS(0), 8)即机器核数与 8 之间的较小值。仓库注释说明实验测得的良好上限是 8 个 worker即使 16 核机器也是如此并注明“可能仍需调优”。错误收集采用预分配切片 errors.Join汇总的方式避免并发追加的锁竞争见 format.go。4. 与其他功能的联动hcl fmt的格式化逻辑还被scaffold命令复用RunForFiles支持只格式化调用方显式指定的文件列表相对/绝对路径均可用于 boilerplate 生成后仅格式化新增文件见 format.go。仓库的 format_test.go 提供了覆盖上述行为的测试用例可作为深入研读的起点。六、CI/CD 集成实战场景一格式门禁check 模式在提交前强制代码格式一致失败即阻断流水线#!/usr/bin/env bash set -euo pipefail terragrunt hcl fmt --check场景二仅格式化变更目录filter exclude-dirterragrunt hcl fmt --filter ./environments/prod/** --exclude-dir.terragrunt-cache场景三编辑器集成stdin通过--stdin可将任何编辑器选中的 HCL 文本就地格式化# 编辑器插件中取选中文本 - 管道输入 - 回填输出 printf resource a b { count 1 } | terragrunt hcl fmt --stdin七、使用注意事项属性过滤不可用hcl fmt --filter typeunit不会生效过滤仅限路径表达式--stdin与--file互斥同时指定会直接报错--check/--diff与--stdin组合时不会输出格式化内容只输出退出码或 diff坏文件不会被改写存在语法错误的 HCL 文件会先被解析器拦截并报错默认会跳过缓存与脚手架目录如需强制格式化其中的文件需自行调整目录结构或改用--file显式指定。综上terragrunt hcl fmt在 Terragrunt 中承担着“配置即代码”的格式统一职责它以官方hclwrite为内核、以并发遍历为手段配合--check、--diff、--filter、--stdin等参数即可在本地、CI 流水线与编辑器集成等场景中无缝复用。【免费下载链接】terragruntTerragrunt is a flexible orchestration tool that allows Infrastructure as Code written in OpenTofu/Terraform to scale.项目地址: https://gitcode.com/GitHub_Trending/te/terragrunt创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Terragrunt hcl fmt 命令完全指南：递归格式化 HCL 文件的原理与实战
Terragrunt hcl fmt 命令完全指南递归格式化 HCL 文件的原理与实战【免费下载链接】terragruntTerragrunt is a flexible orchestration tool that allows Infrastructure as Code written in OpenTofu/Terraform to scale.项目地址: https://gitcode.com/GitHub_Trending/te/terragrunt导读terragrunt hcl fmt是 Terragrunt 提供的 HCL 格式化命令用于递归查找工作目录下所有 HashiCorp Configuration LanguageHCL文件并将其重写为 HashiCorp 官方推荐的规范化格式。本文以 Terragrunt 仓库中该命令的官方文档定义commands 数据文件、flag 定义文件为骨架结合底层实现源码format.go、cli.go展开讲解读完你能够掌握该命令的全部参数、环境变量、退出码约定、CI/CD 集成方式以及其“先语法校验、再并行格式化”的底层实现原理。一、命令概览与定位按照 Terragrunt 官方文档的定义见 hcl/fmt.mdxhcl fmt命令属于configuration类别官方描述为Recursively find HashiCorp Configuration Language (HCL) files and rewrite them into a canonical format.其核心定位有两个关键词Recursively递归默认行为是在工作目录下递归遍历目录树找出所有.hcl文件Canonical format规范化格式重写遵循 HashiCorp 官方语言风格指南即与terraform fmt/tofu fmt完全一致的格式化风格。在命令行中hcl fmt是hcl format子命令的别名。源码 cli.go 中定义const ( CommandName format CommandNameAlias fmt )二、基本用法最简单也是最常用的形式是在 Terragrunt 配置目录下直接执行terragrunt hcl fmt该命令会从当前工作目录opts.WorkingDir出发递归遍历整个目录树对每个.hcl后缀文件执行格式化并写回原文件。从源码 format.go 的遍历逻辑看其默认行为包括仅处理以.hcl结尾的文件strings.HasSuffix(path, .hcl)目录本身会被跳过只收集文件存在一组默认排除目录详见下文第五节。三、命令行参数详解hcl fmt的全部专属参数、环境变量与说明集中定义在 cli.go 与 docs/src/data/flags 目录下的 flag 文档中。下面逐一讲解。1.--check检查模式只检查不修改属性值类型bool环境变量TG_CHECK旧变量TG_HCLFMT_CHECK、TERRAGRUNT_CHECK开启后Terragrunt 只检查 HCL 文件是否已正确格式化不会做任何修改非常适合在 CI/CD 流水线中强制格式一致性所有文件均已正确格式化 → 退出码0存在需要格式化的文件 → 退出码1。terragrunt hcl fmt --check从源码看--check会复用格式化后的内容做字节级比较!bytes.Equal(newContents, contents)一旦发现差异便返回FileNeedsFormattingError见 format.go、errors.go由上层汇总为退出码1。2.--diff打印差异不改写文件属性值类型bool环境变量TG_DIFF旧变量TG_HCLFMT_DIFF、TERRAGRUNT_DIFF开启后Terragrunt 会打印原始版本与格式化版本之间的差异unified diff让你在真正改写之前预览格式化器将要做的改动terragrunt hcl fmt --diff内部实现基于github.com/rogpeppe/go-internal/diff生成 unified diff见 format.godiff 标签统一使用斜杠分隔路径以保证跨平台含 Windows输出一致。3.--exclude-dir排除指定目录属性值类型string可多次指定环境变量TG_EXCLUDE_DIR旧变量TG_HCLFMT_EXCLUDE_DIR、TERRAGRUNT_EXCLUDE_DIR跳过给定目录中的 HCL 文件适合排除vendor、.terragrunt-cache等不需要格式化的目录terragrunt hcl fmt --exclude-dirvendor --exclude-dir.terragrunt-cache注意两点匹配依据是目录的 basenameslices.Contains(opts.HclExclude, basename)见 format.go因此--exclude-dirvendor会排除目录树中任意层级名为vendor的目录该参数与默认排除目录第五节是叠加生效的。4.--file格式化单个文件属性值类型string环境变量TG_FILE旧变量TG_HCLFMT_FILE、TERRAGRUNT_HCLFMT_FILE指定单个 HCL 文件进行格式化替代默认的递归搜索terragrunt hcl fmt --file./environments/prod/terragrunt.hcl相对路径会基于工作目录解析为绝对路径见 format.go。同时指定--file与--stdin会直接报错“both stdin and path flags are specified”。5.--filter基于路径的过滤查询属性值类型list(string)说明对hcl fmt而言只支持路径型过滤表达式--filter在hcl fmt中的行为与其它命令不同它过滤的是单个 HCL 文件而非 unit/stack目录级单位因此只支持基于路径的过滤表达式typeunit、namemy-app这类基于属性的过滤器在此处不可用见 hcl-fmt-filter.mdx。路径匹配支持 glob# 相对路径 glob terragrunt hcl fmt --filter ./envs/prod/** # 格式化特定目录下所有 HCL 文件 terragrunt hcl fmt --filter ./modules/**/*.hcl # 绝对路径 terragrunt hcl fmt --filter /absolute/path/to/envs/dev/apps/*取反!前缀terragrunt hcl fmt --filter !./prod/** terragrunt hcl fmt --filter !./test/**交集 / 精化|运算符# 格式化 prod 目录下的 HCL 文件但排除其中的测试 terragrunt hcl fmt --filter ./prod/** | !./prod/test/** # 格式化所有 HCL 文件排除 test 目录 terragrunt hcl fmt --filter ./**/*.hcl | !./**/test/**并集多个--filterOR 逻辑# 同时格式化 dev 与 staging 两个目录 terragrunt hcl fmt --filter ./dev/** --filter ./staging/**在源码层面收集到全部.hcl文件后会调用filters.EvaluateOnFiles(l, files, workingDir)对文件列表求值见 format.go。更全面的过滤器语法可参考 Filters 功能文档。6.--stdin从标准输入读取并输出到标准输出属性值类型bool环境变量TG_STDIN旧变量TG_HCLFMT_STDIN、TERRAGRUNT_HCLFMT_STDIN从标准输入读取 HCL 内容、格式化后写到标准输出非常适合与编辑器或其他工具集成echo locals { foobar } | terragrunt hcl fmt --stdin与--check/--diff组合时行为不同见 hcl-fmt-stdin.mdx组合--check不打印格式化内容输入需要格式化时退出码为1组合--diff不打印格式化内容打印标签为old/stdin与new/stdin的 unified diff单独使用格式化后的完整内容写入标准输出。对应实现见 format.go其中--check返回FileNeedsFormattingError{Path: stdinPath}。7. 队列与并发参数除上述专属参数外hcl fmt还挂载了一组共享参数见 cli.go--parallelism控制同时格式化的文件数量上限详见第五节队列类参数--queue-exclude-dir、--queue-exclude-external、--queue-excludes-file、--queue-ignore-dag-order、--queue-ignore-errors、--queue-include-dir、--queue-include-external、--queue-include-units-reading、--queue-strict-include用于精细控制遍历范围与错误容忍行为。四、环境变量速查表所有专属 flag 均可通过环境变量设置旧版TG_HCLFMT_*/TERRAGRUNT_*变量仍受支持但已标记废弃flags.WithDeprecatedEnvVars见 cli.go参数新环境变量旧环境变量--checkTG_CHECKTG_HCLFMT_CHECK、TERRAGRUNT_CHECK--diffTG_DIFFTG_HCLFMT_DIFF、TERRAGRUNT_DIFF--exclude-dirTG_EXCLUDE_DIRTG_HCLFMT_EXCLUDE_DIR、TERRAGRUNT_EXCLUDE_DIR--fileTG_FILETG_HCLFMT_FILE、TERRAGRUNT_HCLFMT_FILE--stdinTG_STDINTG_HCLFMT_STDIN、TERRAGRUNT_HCLFMT_STDIN例如在 CI 中可写作TG_CHECKtrue terragrunt hcl fmt五、底层实现原理1. 默认排除目录即使不指定--exclude-dir遍历时也会默认跳过三类目录见 format.govar excludePaths []string{ util.TerragruntCacheDir, // .terragrunt-cache util.DefaultBoilerplateDir, // 模板脚手架相关目录 config.StackDir, // stacks 目录 }匹配发生在vfs.WalkDir回调中命中后直接返回fs.SkipDir剪枝避免无谓下钻见 format.go。2. 格式化内核官方 hcl2 库格式化本身依赖 HashiCorp 官方库github.com/hashicorp/hcl/v2/hclwrite核心只有一行newContents : hclwrite.Format(contents)且格式化前会先用hclparse.NewParser().ParseHCL做一次语法解析checkErrors见 format.go保证“先确认无语法错误、再落盘改写”——解析报错的坏文件不会被盲目改写。只有当新旧内容字节级不一致fileUpdated时才写回文件并保留原文件权限位info.Mode()见 format.go。3. 并发格式化与 worker 上限文件级格式化通过errgroup并行执行。worker 数由formatWorkers决定见 format.go显式指定--parallelism时按用户给定值执行未指定时取min(runtime.GOMAXPROCS(0), 8)即机器核数与 8 之间的较小值。仓库注释说明实验测得的良好上限是 8 个 worker即使 16 核机器也是如此并注明“可能仍需调优”。错误收集采用预分配切片 errors.Join汇总的方式避免并发追加的锁竞争见 format.go。4. 与其他功能的联动hcl fmt的格式化逻辑还被scaffold命令复用RunForFiles支持只格式化调用方显式指定的文件列表相对/绝对路径均可用于 boilerplate 生成后仅格式化新增文件见 format.go。仓库的 format_test.go 提供了覆盖上述行为的测试用例可作为深入研读的起点。六、CI/CD 集成实战场景一格式门禁check 模式在提交前强制代码格式一致失败即阻断流水线#!/usr/bin/env bash set -euo pipefail terragrunt hcl fmt --check场景二仅格式化变更目录filter exclude-dirterragrunt hcl fmt --filter ./environments/prod/** --exclude-dir.terragrunt-cache场景三编辑器集成stdin通过--stdin可将任何编辑器选中的 HCL 文本就地格式化# 编辑器插件中取选中文本 - 管道输入 - 回填输出 printf resource a b { count 1 } | terragrunt hcl fmt --stdin七、使用注意事项属性过滤不可用hcl fmt --filter typeunit不会生效过滤仅限路径表达式--stdin与--file互斥同时指定会直接报错--check/--diff与--stdin组合时不会输出格式化内容只输出退出码或 diff坏文件不会被改写存在语法错误的 HCL 文件会先被解析器拦截并报错默认会跳过缓存与脚手架目录如需强制格式化其中的文件需自行调整目录结构或改用--file显式指定。综上terragrunt hcl fmt在 Terragrunt 中承担着“配置即代码”的格式统一职责它以官方hclwrite为内核、以并发遍历为手段配合--check、--diff、--filter、--stdin等参数即可在本地、CI 流水线与编辑器集成等场景中无缝复用。【免费下载链接】terragruntTerragrunt is a flexible orchestration tool that allows Infrastructure as Code written in OpenTofu/Terraform to scale.项目地址: https://gitcode.com/GitHub_Trending/te/terragrunt创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考