chezmoi 使用 `.chezmoidata.$FORMAT` 注入静态模板数据：格式、合并规则与源码原理

chezmoi 使用.chezmoidata.$FORMAT注入静态模板数据格式、合并规则与源码原理【免费下载链接】chezmoiManage your dotfiles across multiple diverse machines, securely.项目地址: https://gitcode.com/gh_mirrors/ch/chezmoi本文围绕 chezmoi 源码状态中的特殊数据文件.chezmoidata.$FORMAT展开讲解如何用 JSON、JSONC、TOML、YAML 四种格式为模板引擎预置结构化静态数据说明多个数据文件的词法排序合并规则、字典递归合并与其余类型整体替换的行为并给出用chezmoi data验证结果的完整实操。读完本文你将掌握在 chezmoi 的模板中使用.fontSize这类全局数据变量的标准姿势并理解它与.chezmoidata/目录、data配置段之间的分工边界。一、.chezmoidata.$FORMAT是什么在 chezmoi 的源码状态source state中只要存在名为.chezmoidata.$FORMAT的文件它就会被解释为给定格式的结构化静态数据。这些数据随后可以在所有模板中作为点号根变量如.fontSize直接使用。$FORMAT支持四种格式JSON、JSONC、TOML、YAML这一点在 config-format.md 中明确列出且格式解析由 internal/chezmoi/format.go 中的FormatJSON、FormatJSONC、FormatTOML、FormatYAML四种实现承载。与它配套的还有一种组织形式.chezmoidata/目录目录内所有文件同样会被当作结构化数据读取。两者的语义一致相关说明见.chezmoidata/。最小示例让模板读到fontSize假如~/.local/share/chezmoi/.chezmoidata.toml内容如下fontSize 12那么在任意模板如dot_config/foo.tmpl中.fontSize变量即变为可用FONT_SIZE{{ .fontSize }}渲染结果是FONT_SIZE12这里的关键在于数据文件必须位于源码状态目录内默认即~/.local/share/chezmoi/并且文件名精确匹配.chezmoidata.toml这类带格式后缀的形式。源码中通过isPrefixDotFormat(fileInfo.Name(), dataName)internal/chezmoi/format.go判断凡是.chezmoidata.后跟任一已知格式扩展名的文件都会被识别并交给addTemplateData处理。二、支持的四种格式与解析入口.chezmoidata.$FORMAT中$FORMAT的取值由扩展名决定与 chezmoi 配置文件一致支持扩展名格式解析实现.jsonJSONformat.goFormatJSON.jsoncJSON with Comments带注释与尾逗号的 JSONformat.goFormatJSONC.tomlTOMLformat.goFormatTOML.yaml/.ymlYAMLformat.goFormatYAML从源码看addTemplateDatainternal/chezmoi/sourcestate.go首先用FormatFromAbsPath(sourceAbsPath)依据扩展名解析出对应Format然后调用format.Unmarshal(data, templateData)把文件内容反序列化为map[string]any最后合并进s.userTemplateData。这一过程发生在模板引擎启动之前源码状态读取时switch分支internal/chezmoi/sourcestate.go会在遍历源码目录时专门捕获dataName即.chezmoidata与isPrefixDotFormat(fileInfo.Name(), dataName)两类文件并执行addTemplateDataDir或addTemplateData这正是下文“数据文件不能是模板”这一约束的根源。三、多文件合并词法排序 字典递归合并源码状态中可以存在多个.chezmoidata.$FORMAT文件它们全部合并到数据字典data dictionary的根上读取顺序为文件系统下的词法字母序顺序。合并示例四种格式的 z 字典以dot_config源码目录下的四个文件为例{ z: { z: 3 } }{ z: { z: 4 } }z.x 1z: y: 2按文件名词法排序读取顺序为.chezmoidata.json→.chezmoidata.jsonc→.chezmoidata.toml→.chezmoidata.yaml。因此.chezmoidata.jsonc中z.z 4会覆盖.chezmoidata.json中的z.z 3后读覆盖先读最终chezmoi data输出的合并结果为{ z: { x: 1, y: 2, z: 4 } }注意.chezmoidata.toml的z.x、.chezmoidata.yaml的z.y分别作为新键并入而非整体替换z字典。源码层面的合并实现上述行为由 internal/chezmoi/recursivemerge.go 的RecursiveMerge保证目标字典中不存在的键直接复制源值目标字典中已存在的键且两侧值都是map[string]any递归向下合并字典其余所有情况包括键已存在但值不是字典、或源值不是字典用源值整体替换目标值。这直接解释了文档中的一条硬性规则——只有字典会被递归合并其他值尤其是列表一律整体替换。例如若两个数据文件都定义了colors列表后读文件的colors会完全覆盖先读文件的值而不是拼接。addTemplateData每次读取一个文件后都会调用RecursiveMerge(s.userTemplateData, templateData)并把缓存的s.templateData置空internal/chezmoi/sourcestate.go保证合并结果在下一次TemplateData()调用时重新生效。四、数据文件的读取顺序与.chezmoidata/目录.chezmoidata/目录内的文件遵循同样的规则文件间按词法顺序合并目录与目录之间也按词法顺序合并最终同样合并到数据字典的根。典型示例如下参见.chezmoidata/{ z: { z: 3 } }{ z: { z: 4 } }z.x 1z: y: 2按文件名排序后读取顺序为alpha.jsonc→beta.toml→gamma.yaml→zed.json因此zed.json的z.z 3覆盖了alpha.jsonc的z.z 4合并结果中z为{x: 1, y: 2, z: 3}。从源码看addTemplateDataDirinternal/chezmoi/sourcestate.go会遍历.chezmoidata/目录以.开头的特殊文件Prefix被禁止放入该目录常规文件逐个交给addTemplateData处理同时目录内不允许出现模板以.tmpl结尾——这与.chezmoidata.$FORMAT文件“不能是模板”的限制一脉相承源码里isPrefixDotFormat只匹配纯格式扩展名而isPrefixDotFormatDotTmplinternal/chezmoi/format.go才匹配带.tmpl后缀的变体后者用于.chezmoi.$FORMAT.tmpl这类配置模板而非数据文件。命名建议由于合并结果对同名键后者覆盖前者若希望某个文件的优先级更高可以在文件命名上利用词法顺序例如把需要“垫底”的默认值放在以字母序更靠前的名字如00-defaults.json把需要覆盖默认值的机器特定值放在靠后的名字如99-overrides.json。这一技巧对.chezmoidata.$FORMAT文件与.chezmoidata/目录内文件同样适用。五、验证合并结果chezmoi datachezmoi data命令会输出完整的模板数据字典。它通过WithTemplateDataOnly(true)构建源码状态并调用sourceState.TemplateData()internal/cmd/datacmd.go因此可以直观看到所有.chezmoidata.*文件合并后的最终形态是排查数据覆盖问题的最直接手段。例如上文的四文件合并示例执行后z字典即如第三节所示。TemplateData()internal/chezmoi/sourcestate.go内部按固定优先级递归合并三类数据源defaultTemplateDatachezmoi 内置的默认数据含.chezmoi元信息userTemplateData来自.chezmoidata.$FORMAT文件与.chezmoidata/目录的数据priorityTemplateData来自配置data段的高优先级数据。后合并者覆盖先合并者因此配置段data中的动态机器数据优先级高于静态数据文件。六、重要限制数据文件不能是模板!!! warning明确指出.chezmoidata.$FORMAT文件不能是模板。原因在于模板引擎尚未启动之前这些数据文件就必须已就位模板渲染如.chezmoi.toml.tmpl对配置的求值反过来还要依赖这些数据。源码也印证了这一点addTemplateData直接ReadFile后format.Unmarshal解析为静态字典全程不经过模板执行器internal/chezmoi/sourcestate.go。对不同类型的动态数据文档给出两条明确出路动态机器数据如主机名、操作系统、架构等随机器变化的值应放在.chezmoi.$FORMAT.tmpl配置文件的data段中让模板配置先计算再注入数据动态环境数据运行时才能获取的外部信息应在模板中通过函数实时读取推荐output、fromJson、fromYaml等模板函数。对应的函数参考文档为 output、fromJson 与 fromYaml。例如{{ $data : output some-command | fromJson }} VALUE{{ $data.field }}这样的写法允许在模板渲染阶段拉取命令输出或外部文件再解析为结构化数据使用与静态数据文件形成互补。七、数据文件在测试中的实际用法仓库的 txtar 集成测试 templatedata.txtar 提供了数据文件与模板联动的端到端证据测试创建了一个包含.chezmoidata.toml内容filename .file2、.chezmoiignore与.chezmoitemplates/ignore的源码状态.chezmoiignore中通过{{ template ignore . }}引用模板而该模板内部使用{{ .filename }}——这里的.filename正是来自.chezmoidata.toml的数据最终chezmoi apply的结果是$HOME/.file1被创建、.file2被忽略证明数据文件的值确实进入了模板上下文并影响实际行为。这组测试同时验证了另一条事实.chezmoidata.*的数据不仅可用于目标文件模板也可以被.chezmoiignore等控制文件中的模板引用只要这些模板的求值发生在数据加载之后。八、总结与最佳实践.chezmoidata.$FORMAT.json/.jsonc/.toml/.yaml与.chezmoidata/目录用于向模板提供静态、结构化的数据以.变量名的形式在任意模板中访问多个数据文件按文件名词法顺序依次合并到数据字典根上同名键后者覆盖前者字典递归合并其他类型含列表整体替换——这是 recursivemerge.go 定义的核心语义用chezmoi data随时查看合并后的完整数据字典用它来验证覆盖关系数据文件不可模板化机器动态数据放配置data段环境动态数据用output/fromJson/fromYaml在模板内实时获取需要覆盖默认值时利用词法顺序把高优先级数据放到字母序更靠后的文件名中。掌握这套规则后你可以把常见的跨机器差异如字体大小、编辑器偏好、用户名邮箱等沉淀为静态数据文件让所有模板统一消费同时保持数据与模板逻辑清晰分离。【免费下载链接】chezmoiManage your dotfiles across multiple diverse machines, securely.项目地址: https://gitcode.com/gh_mirrors/ch/chezmoi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考