chezmoi 模板函数includeTemplate完全指南复用.chezmoitemplates模板并传入上下文数据【免费下载链接】chezmoiManage your dotfiles across multiple diverse machines, securely.项目地址: https://gitcode.com/gh_mirrors/ch/chezmoi导读includeTemplate是 chezmoi 内置的模板函数之一用于在当前模板中执行另一个模板文件的内容并可按需向被包含的模板传入上下文数据.data。它区别于只做文本原样读取的include函数被包含的文件会先被当作 Gotext/template模板解析执行再返回执行结果。本文以 includeTemplate.md 官方参考文档为骨架结合源码实现与 txtar 集成测试系统讲解其语法、路径查找顺序、与include/templateaction 的区别及实战用法帮助你写出可复用的点文件模板。函数签名与核心语义官方文档给出了完整的函数签名includeTemplate *filename* [*data*]其语义可以概括为三点执行而非读取includeTemplate返回的是“执行filename文件内容”的结果。也就是说文件内容会被当作模板解析其中的{{ ... }}指令会真实执行这与只返回文件原始文本的include函数有本质区别。可选数据参数调用时可以附带一个可选的data参数该参数会成为被包含模板执行时的上下文值即模板中的.。不传时被包含模板以nil上下文执行。两级路径查找相对路径首先在.chezmoitemplates目录中查找如果找不到再相对于**源目录source directory**解释。源码 internal/cmd/templatefuncs.go 中includeTemplateTemplateFunc的实现完整印证了这些语义func (c *Config) includeTemplateTemplateFunc(filename string, args ...any) string { var data any switch len(args) { case 0: // Do nothing. case 1: data args[0] default: panic(fmt.Errorf(expected 0 or 1 arguments, got %d, len(args))) } searchDirAbsPaths : []chezmoi.AbsPath{ c.sourceDirAbsPath.JoinString(chezmoi.TemplatesDirName), c.sourceDirAbsPath, } contents : mustValue(c.readFile(filename, searchDirAbsPaths)) tmpl : mustValue(chezmoi.ParseTemplate(filename, contents, chezmoi.TemplateOptions{ Funcs: c.templateFuncs, Options: slices.Clone(c.Template.Options), })) return string(mustValue(tmpl.Execute(data))) }从源码可以归纳出几个关键实现细节参数个数限制args只接受 0 个或 1 个参数。传入 2 个及以上参数时会直接panic错误信息为expected 0 or 1 arguments, got N。因此在使用时务必只传最多一个数据参数。查找顺序searchDirAbsPaths数组的顺序是“先.chezmoitemplates后源目录”这与文档描述完全一致。其中TemplatesDirName即.chezmoitemplates目录名常量。模板上下文继承被包含的模板在解析时复用了当前 chezmoi 会话的templateFuncs所有内置模板函数都可用以及Template.Options如缺失键处理、可选值等配置因此被包含模板与调用方共享同一套模板能力行为保持一致。执行结果通过tmpl.Execute(data)执行data即调用方传入的第二个参数未传时为零值nil。该函数在 internal/cmd/config.go 中注册进模板函数表include: c.includeTemplateFunc, includeTemplate: c.includeTemplateTemplateFunc,与include函数、templateaction 的区别在 chezmoi 中有三种“引入其他文件”的方式理解它们的差异是正确选型的前提方式行为适用场景includefilename返回文件原始文本内容不执行模板指令见 include.md引入纯文本片段如许可证文本、静态配置块includeTemplatefilename[data]将文件内容作为模板解析并执行可传上下文数据引入含模板指令、依赖数据上下文的可复用模板{{ template name . }}action执行已定义的模板由define或.chezmoitemplates隐式定义上下文需显式传递在同一模板渲染流程内复用已命名的模板块三个关键差异点是否执行模板include不执行、includeTemplate和templateaction 都会执行。上下文.处理includeTemplate通过第二个参数显式传入 data 作为上下文而templateaction 必须自行传.否则以nil上下文执行官方.chezmoitemplates文档特别强调了这一点。来源范围include只相对源目录查找includeTemplate先在.chezmoitemplates查找再回落源目录templateaction 只能引用已定义的模板.chezmoitemplates中的文件天然具备这种“以相对路径命名”的模板身份。路径查找顺序详解includeTemplate的相对路径解析遵循以下顺序源码 internal/cmd/templatefuncs.go 中readFile按searchDirAbsPaths顺序逐个尝试首先在.chezmoitemplates/目录下查找filename若该目录下不存在则在源目录通常为~/.local/share/chezmoi下按filename查找若两处都不存在则报错文件不存在。底层readFile的实现如下func (c *Config) readFile(filename string, searchDirAbsPaths []chezmoi.AbsPath) ([]byte, error) { if filepath.IsAbs(filename) { absPath, err : chezmoi.NewAbsPathFromExtPath(filename, c.homeDirAbsPath) if err ! nil { return nil, err } return c.fileSystem.ReadFile(absPath.String()) } // 相对路径按 searchDirAbsPaths 顺序逐个尝试 for _, searchDir : range searchDirAbsPaths { data, err c.fileSystem.ReadFile(searchDir.JoinString(filename).String()) if !errors.Is(err, fs.ErrNotExist) { return data, err } } return data, err }从源码可以看出如果传入的是绝对路径则直接以该路径读取文件不再走.chezmoitemplates/源目录的查找逻辑。推荐目录组织方式.chezmoitemplates是 chezmoi 的特殊目录。官方文档chezmoitemplates.md说明只要源状态中存在任何名为.chezmoitemplates/的目录其中所有文件都会以“相对于该目录的路径”作为模板名供templateaction 或includeTemplate函数引用。虽然.chezmoitemplates/可以位于源状态中的任意位置但官方建议在源目录根下维护单一目录便于管理。一个典型的布局~/.local/share/chezmoi/ ├── .chezmoitemplates/ │ ├── header # 可被 includeTemplate 引用的模板片段 │ ├── ssh-config # 含模板指令依赖数据上下文 │ └── ... ├── dot_config/ # 源文件 └── dot_bashrc.tmpl实战示例示例一基础用法——从.chezmoitemplates引入模板假设源目录下有如下文件~/.local/share/chezmoi/.chezmoitemplates/foo{{ if true }}bar{{ end }}在dot_file.tmpl中引入它{{ includeTemplate foo }}渲染后目标文件内容为bar——模板指令被真实执行。官方.chezmoitemplates文档中的示例使用了{{ template foo . }}达到同样的效果两种方式均可。示例二传入上下文数据includeTemplate最强大的地方在于可以传入数据参数让被包含模板按数据动态渲染。例如.chezmoitemplates/ssh-config模板片段Host {{ .host }} HostName {{ .hostname }} User {{ .user }}在主模板中传入数据{{ includeTemplate ssh-config (dict host myserver hostname example.com user alice) }}执行结果Host myserver HostName example.com User alice注意数据参数必须恰好一个。传多个参数会触发源码中的panicexpected 0 or 1 arguments, got N。示例三相对源目录的回落查找如果filename在.chezmoitemplates中不存在chezmoi 会相对源目录查找。例如源目录中存在scripts/common.tmpl#!/usr/bin/env bash set -euo pipefail {{ .extra }}在模板中引用{{ includeTemplate scripts/common.tmpl (dict extra echo done) }}与include的对比示例include只返回文件原始文本{{ include LICENSE }} {{/* 返回 LICENSE 文件原样内容模板指令不执行 */}} {{ includeTemplate banner }} {{/* banner 内容会被当作模板执行 */}}测试用例印证仓库中的 txtar 集成测试templatefuncs.txtar直接验证了includeTemplate的两个核心行为# test includeTemplate template function exec chezmoi execute-template {{ includeTemplate .template data }} stdout ^data$ # test includeTemplate template function searches .chezmoitemplates exec chezmoi execute-template {{ includeTemplate template data }} stdout ^data$第一条通过execute-template子命令执行{{ includeTemplate .template data }}输出被断言为data验证了文件内容作为模板执行后返回结果、且传入的 data 会成为模板输出。第二条以不带.前缀的名称template引用验证了includeTemplate会在.chezmoitemplates目录中查找模板文件。另一组测试 issue4002.txtar 则覆盖了一个重要边界场景当源目录存在.chezmoiroot源目录重定向配置时无论是重新初始化还是裸init --applyincludeTemplate都能正确定位.chezmoitemplates中的模板。测试构造的源状态为-- home/user/.local/share/chezmoi/.chezmoiroot -- home -- home/user/.local/share/chezmoi/home/.chezmoi.toml.tmpl -- {{- includeTemplate template -}} -- home/user/.local/share/chezmoi/home/.chezmoitemplates/template -- # contents of template该测试说明.chezmoitemplates的查找会遵循.chezmoiroot重定向后的源目录根模板解析与配置生成在初始化流程中均正常工作。结合execute-template子命令快速验证在日常开发中你可以用chezmoi execute-template子命令脱离完整源状态快速验证includeTemplate的语法与渲染结果# 直接内联测试需存在对应文件 chezmoi execute-template {{ includeTemplate .template data }} # 渲染整个模板文件 chezmoi execute-template dot_file.tmpl这在调试模板片段、验证数据字典结构时非常高效。使用建议与注意事项优先把可复用片段放进.chezmoitemplates/根目录让includeTemplate与templateaction 都能以简洁的名称引用把目录放在源目录根部查找路径最短、意图最清晰。严格限制数据参数为 0 或 1 个多个参数会直接导致模板执行 panic。需要执行模板就用includeTemplate只需要原样文本就用include避免因误用include导致{{ ... }}指令被原样输出到目标文件。上下文数据缺失时被包含模板以nil上下文执行模板中引用.字段会失败务必在需要时显式传 data。templateaction 是另一种等效手段.chezmoitemplates中的文件天然以相对路径命名也可通过{{ template foo . }}引入上下文需显式传.两者可以按场景自由选择。小结includeTemplate是 chezmoi 模板体系中实现“模板复用”的核心函数它把.chezmoitemplates与源目录中的文件当作可执行模板引入当前渲染流程并支持传入上下文数据实现动态化输出。理解其“先.chezmoitemplates、后源目录”的查找顺序、与include/templateaction 的差异以及数据参数的限制就能在多机点文件管理中优雅地抽取公共片段减少重复、提升可维护性。相关实现细节可继续阅读 templatefuncs.go、config.go 与特殊目录文档 chezmoitemplates.md。【免费下载链接】chezmoiManage your dotfiles across multiple diverse machines, securely.项目地址: https://gitcode.com/gh_mirrors/ch/chezmoi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 chezmoi 模板函数 `includeTemplate` 完全指南：复用 `.chezmoitemplates` 模板并传入上下文数据
chezmoi 模板函数includeTemplate完全指南复用.chezmoitemplates模板并传入上下文数据【免费下载链接】chezmoiManage your dotfiles across multiple diverse machines, securely.项目地址: https://gitcode.com/gh_mirrors/ch/chezmoi导读includeTemplate是 chezmoi 内置的模板函数之一用于在当前模板中执行另一个模板文件的内容并可按需向被包含的模板传入上下文数据.data。它区别于只做文本原样读取的include函数被包含的文件会先被当作 Gotext/template模板解析执行再返回执行结果。本文以 includeTemplate.md 官方参考文档为骨架结合源码实现与 txtar 集成测试系统讲解其语法、路径查找顺序、与include/templateaction 的区别及实战用法帮助你写出可复用的点文件模板。函数签名与核心语义官方文档给出了完整的函数签名includeTemplate *filename* [*data*]其语义可以概括为三点执行而非读取includeTemplate返回的是“执行filename文件内容”的结果。也就是说文件内容会被当作模板解析其中的{{ ... }}指令会真实执行这与只返回文件原始文本的include函数有本质区别。可选数据参数调用时可以附带一个可选的data参数该参数会成为被包含模板执行时的上下文值即模板中的.。不传时被包含模板以nil上下文执行。两级路径查找相对路径首先在.chezmoitemplates目录中查找如果找不到再相对于**源目录source directory**解释。源码 internal/cmd/templatefuncs.go 中includeTemplateTemplateFunc的实现完整印证了这些语义func (c *Config) includeTemplateTemplateFunc(filename string, args ...any) string { var data any switch len(args) { case 0: // Do nothing. case 1: data args[0] default: panic(fmt.Errorf(expected 0 or 1 arguments, got %d, len(args))) } searchDirAbsPaths : []chezmoi.AbsPath{ c.sourceDirAbsPath.JoinString(chezmoi.TemplatesDirName), c.sourceDirAbsPath, } contents : mustValue(c.readFile(filename, searchDirAbsPaths)) tmpl : mustValue(chezmoi.ParseTemplate(filename, contents, chezmoi.TemplateOptions{ Funcs: c.templateFuncs, Options: slices.Clone(c.Template.Options), })) return string(mustValue(tmpl.Execute(data))) }从源码可以归纳出几个关键实现细节参数个数限制args只接受 0 个或 1 个参数。传入 2 个及以上参数时会直接panic错误信息为expected 0 or 1 arguments, got N。因此在使用时务必只传最多一个数据参数。查找顺序searchDirAbsPaths数组的顺序是“先.chezmoitemplates后源目录”这与文档描述完全一致。其中TemplatesDirName即.chezmoitemplates目录名常量。模板上下文继承被包含的模板在解析时复用了当前 chezmoi 会话的templateFuncs所有内置模板函数都可用以及Template.Options如缺失键处理、可选值等配置因此被包含模板与调用方共享同一套模板能力行为保持一致。执行结果通过tmpl.Execute(data)执行data即调用方传入的第二个参数未传时为零值nil。该函数在 internal/cmd/config.go 中注册进模板函数表include: c.includeTemplateFunc, includeTemplate: c.includeTemplateTemplateFunc,与include函数、templateaction 的区别在 chezmoi 中有三种“引入其他文件”的方式理解它们的差异是正确选型的前提方式行为适用场景includefilename返回文件原始文本内容不执行模板指令见 include.md引入纯文本片段如许可证文本、静态配置块includeTemplatefilename[data]将文件内容作为模板解析并执行可传上下文数据引入含模板指令、依赖数据上下文的可复用模板{{ template name . }}action执行已定义的模板由define或.chezmoitemplates隐式定义上下文需显式传递在同一模板渲染流程内复用已命名的模板块三个关键差异点是否执行模板include不执行、includeTemplate和templateaction 都会执行。上下文.处理includeTemplate通过第二个参数显式传入 data 作为上下文而templateaction 必须自行传.否则以nil上下文执行官方.chezmoitemplates文档特别强调了这一点。来源范围include只相对源目录查找includeTemplate先在.chezmoitemplates查找再回落源目录templateaction 只能引用已定义的模板.chezmoitemplates中的文件天然具备这种“以相对路径命名”的模板身份。路径查找顺序详解includeTemplate的相对路径解析遵循以下顺序源码 internal/cmd/templatefuncs.go 中readFile按searchDirAbsPaths顺序逐个尝试首先在.chezmoitemplates/目录下查找filename若该目录下不存在则在源目录通常为~/.local/share/chezmoi下按filename查找若两处都不存在则报错文件不存在。底层readFile的实现如下func (c *Config) readFile(filename string, searchDirAbsPaths []chezmoi.AbsPath) ([]byte, error) { if filepath.IsAbs(filename) { absPath, err : chezmoi.NewAbsPathFromExtPath(filename, c.homeDirAbsPath) if err ! nil { return nil, err } return c.fileSystem.ReadFile(absPath.String()) } // 相对路径按 searchDirAbsPaths 顺序逐个尝试 for _, searchDir : range searchDirAbsPaths { data, err c.fileSystem.ReadFile(searchDir.JoinString(filename).String()) if !errors.Is(err, fs.ErrNotExist) { return data, err } } return data, err }从源码可以看出如果传入的是绝对路径则直接以该路径读取文件不再走.chezmoitemplates/源目录的查找逻辑。推荐目录组织方式.chezmoitemplates是 chezmoi 的特殊目录。官方文档chezmoitemplates.md说明只要源状态中存在任何名为.chezmoitemplates/的目录其中所有文件都会以“相对于该目录的路径”作为模板名供templateaction 或includeTemplate函数引用。虽然.chezmoitemplates/可以位于源状态中的任意位置但官方建议在源目录根下维护单一目录便于管理。一个典型的布局~/.local/share/chezmoi/ ├── .chezmoitemplates/ │ ├── header # 可被 includeTemplate 引用的模板片段 │ ├── ssh-config # 含模板指令依赖数据上下文 │ └── ... ├── dot_config/ # 源文件 └── dot_bashrc.tmpl实战示例示例一基础用法——从.chezmoitemplates引入模板假设源目录下有如下文件~/.local/share/chezmoi/.chezmoitemplates/foo{{ if true }}bar{{ end }}在dot_file.tmpl中引入它{{ includeTemplate foo }}渲染后目标文件内容为bar——模板指令被真实执行。官方.chezmoitemplates文档中的示例使用了{{ template foo . }}达到同样的效果两种方式均可。示例二传入上下文数据includeTemplate最强大的地方在于可以传入数据参数让被包含模板按数据动态渲染。例如.chezmoitemplates/ssh-config模板片段Host {{ .host }} HostName {{ .hostname }} User {{ .user }}在主模板中传入数据{{ includeTemplate ssh-config (dict host myserver hostname example.com user alice) }}执行结果Host myserver HostName example.com User alice注意数据参数必须恰好一个。传多个参数会触发源码中的panicexpected 0 or 1 arguments, got N。示例三相对源目录的回落查找如果filename在.chezmoitemplates中不存在chezmoi 会相对源目录查找。例如源目录中存在scripts/common.tmpl#!/usr/bin/env bash set -euo pipefail {{ .extra }}在模板中引用{{ includeTemplate scripts/common.tmpl (dict extra echo done) }}与include的对比示例include只返回文件原始文本{{ include LICENSE }} {{/* 返回 LICENSE 文件原样内容模板指令不执行 */}} {{ includeTemplate banner }} {{/* banner 内容会被当作模板执行 */}}测试用例印证仓库中的 txtar 集成测试templatefuncs.txtar直接验证了includeTemplate的两个核心行为# test includeTemplate template function exec chezmoi execute-template {{ includeTemplate .template data }} stdout ^data$ # test includeTemplate template function searches .chezmoitemplates exec chezmoi execute-template {{ includeTemplate template data }} stdout ^data$第一条通过execute-template子命令执行{{ includeTemplate .template data }}输出被断言为data验证了文件内容作为模板执行后返回结果、且传入的 data 会成为模板输出。第二条以不带.前缀的名称template引用验证了includeTemplate会在.chezmoitemplates目录中查找模板文件。另一组测试 issue4002.txtar 则覆盖了一个重要边界场景当源目录存在.chezmoiroot源目录重定向配置时无论是重新初始化还是裸init --applyincludeTemplate都能正确定位.chezmoitemplates中的模板。测试构造的源状态为-- home/user/.local/share/chezmoi/.chezmoiroot -- home -- home/user/.local/share/chezmoi/home/.chezmoi.toml.tmpl -- {{- includeTemplate template -}} -- home/user/.local/share/chezmoi/home/.chezmoitemplates/template -- # contents of template该测试说明.chezmoitemplates的查找会遵循.chezmoiroot重定向后的源目录根模板解析与配置生成在初始化流程中均正常工作。结合execute-template子命令快速验证在日常开发中你可以用chezmoi execute-template子命令脱离完整源状态快速验证includeTemplate的语法与渲染结果# 直接内联测试需存在对应文件 chezmoi execute-template {{ includeTemplate .template data }} # 渲染整个模板文件 chezmoi execute-template dot_file.tmpl这在调试模板片段、验证数据字典结构时非常高效。使用建议与注意事项优先把可复用片段放进.chezmoitemplates/根目录让includeTemplate与templateaction 都能以简洁的名称引用把目录放在源目录根部查找路径最短、意图最清晰。严格限制数据参数为 0 或 1 个多个参数会直接导致模板执行 panic。需要执行模板就用includeTemplate只需要原样文本就用include避免因误用include导致{{ ... }}指令被原样输出到目标文件。上下文数据缺失时被包含模板以nil上下文执行模板中引用.字段会失败务必在需要时显式传 data。templateaction 是另一种等效手段.chezmoitemplates中的文件天然以相对路径命名也可通过{{ template foo . }}引入上下文需显式传.两者可以按场景自由选择。小结includeTemplate是 chezmoi 模板体系中实现“模板复用”的核心函数它把.chezmoitemplates与源目录中的文件当作可执行模板引入当前渲染流程并支持传入上下文数据实现动态化输出。理解其“先.chezmoitemplates、后源目录”的查找顺序、与include/templateaction 的差异以及数据参数的限制就能在多机点文件管理中优雅地抽取公共片段减少重复、提升可维护性。相关实现细节可继续阅读 templatefuncs.go、config.go 与特殊目录文档 chezmoitemplates.md。【免费下载链接】chezmoiManage your dotfiles across multiple diverse machines, securely.项目地址: https://gitcode.com/gh_mirrors/ch/chezmoi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考