chezmoi 模板函数 pass / passFields / passRaw：在点文件模板中安全读取 pass 密码库

chezmoi 模板函数 pass / passFields / passRaw在点文件模板中安全读取 pass 密码库【免费下载链接】chezmoiManage your dotfiles across multiple diverse machines, securely.项目地址: https://gitcode.com/gh_mirrors/ch/chezmoi导读chezmoi 是一套跨机器管理点文件dotfiles的工具其核心能力之一是在模板中动态注入敏感数据如密码、登录名。pass、passFields、passRaw是 chezmoi 为 passthe standard unix password manager 提供的三个模板函数它们让模板可以在渲染时调用本机的passCLI 从密码库中读取密码及结构化元数据而无需把明文密钥写进点文件仓库。阅读本文后你将掌握三个函数的行为差异、底层实现原理、配置方式包括改用 passage 等 pass 兼容客户端以及对应的测试验证方法。功能总览三个 pass 系列模板函数chezmoi 官方文档在 assets/chezmoi.io/docs/reference/templates/pass-functions/index.md 中对pass系列函数给出了统一定义它们都通过 pass CLIpass返回存储在 pass 密码库中的密码。三个函数的区别如下模板函数签名返回值缓存passpass *pass-name*pass show $PASS_NAME输出的第一行并去掉尾部换行是passFieldspassFields *pass-name*将输出按行解析为「冒号分隔的键值对」得到的 map是共享底层缓存passRawpassRaw *pass-name*pass show $PASS_NAME的完整原始输出是三个函数均接受一个pass-name参数等价于执行pass show $PASS_NAME。缓存机制保证同一pass-name在一次渲染过程中只会真正调用一次pass命令避免重复执行外部程序带来的开销与可能的 pinentry 弹窗。pass取第一行作为密码行为约定pass返回pass show $PASS_NAME输出的第一行并去掉尾部换行。由于 pass 的惯例是把密码写在条目的第一行、附加字段写在后续行因此pass恰好返回「纯密码」。官方文档给出的最小用法示例为{{ pass $PASS_NAME }}例如{{ pass email/example }}源码级实现在 internal/cmd/passtemplatefuncs.go 中pass的实现如下func (c *Config) passTemplateFunc(id string) string { chezmoi.SkipTemplateIf(c.skipSecrets) output : mustValue(c.passOutput(id)) firstLine, _, _ : bytes.Cut(output, []byte{\n}) return string(bytes.TrimSpace(firstLine)) }要点通过bytes.Cut(output, []byte{\n})截取第一个换行符之前的内容得到第一行再经bytes.TrimSpace去掉首尾空白保证返回的密码不带多余换行或空格c.skipSecrets被置位时如执行chezmoi execute-template --skip-secrets之类场景chezmoi.SkipTemplateIf会跳过模板执行防止敏感数据被意外渲染。passFields解析结构化键值对行为约定passFields将pass show $PASS_NAME的完整输出按行解析为「冒号分隔的键值对」返回map[string]string。解析规则为每一行如果包含冒号则冒号左侧作为 key、右侧作为 value且两侧的空白会被裁剪不含冒号的行被忽略。官方文档示例给定pass输出GitHub login: username password: secretpassFields返回的 map 为{ login: username, password: secret }使用方式{{ (passFields GitHub).password }}该表达式渲染为secret。源码级实现在 internal/cmd/passtemplatefuncs.go 中func (c *Config) passFieldsTemplateFunc(id string) map[string]string { chezmoi.SkipTemplateIf(c.skipSecrets) output : mustValue(c.passOutput(id)) result : make(map[string]string) for line : range bytes.SplitSeq(output, []byte{\n}) { if key, value, ok : bytes.Cut(line, []byte{:}); ok { result[string(bytes.TrimSpace(key))] string(bytes.TrimSpace(value)) } } return result }实现细节按\n切分完整输出逐行处理使用bytes.Cut(line, []byte{:})找到第一个冒号作为分隔点——这意味着 value 内部即使再包含冒号也能被完整保留key 与 value 均做bytes.TrimSpace处理不含冒号的行如示例中的首行GitHub被跳过不影响结果与pass共用passOutput因此同一pass-name的pass与passFields调用同样只触发一次外部命令。提示如果同一条目中某个 key 需要以非字符串形式使用如端口号可以结合fromJson、atoi等模板函数做类型转换passFields本身返回的是字符串 map。passRaw获取完整原始输出passRaw返回pass show $PASS_NAME的完整输出不做第一行截取、不做键值对解析适合需要读取多行内容或保留原始格式的场景。官方文档passRaw.md同样注明输出会被缓存多次调用同一pass-name只执行一次pass。源码实现internal/cmd/passtemplatefuncs.gofunc (c *Config) passRawTemplateFunc(id string) string { chezmoi.SkipTemplateIf(c.skipSecrets) return string(mustValue(c.passOutput(id))) }底层实现passOutput与缓存机制三个函数最终都汇聚到同一个私有方法passOutputinternal/cmd/passtemplatefuncs.gofunc (c *Config) passOutput(id string) ([]byte, error) { if output, ok : c.Pass.cache[id]; ok { return output, nil } args : []string{show, id} cmd : exec.Command(c.Pass.Command, args...) cmd.Stdin os.Stdin cmd.Stderr os.Stderr output, err : chezmoilog.LogCmdOutput(c.logger, cmd) if err ! nil { return nil, newCmdOutputError(cmd, output, err) } if c.Pass.cache nil { c.Pass.cache make(map[string][]byte) } c.Pass.cache[id] output return output, nil }其工作机制可从源码中直接确认参数构造固定以show pass-name作为参数执行pass命令标准输入透传cmd.Stdin os.Stdin、cmd.Stderr os.Stderr因此 pass 的交互式输入如 pinentry 中的 GPG 口令输入可以正常工作输出日志通过chezmoilog.LogCmdOutput执行并记录命令输出可用于调试排查错误处理执行失败时返回newCmdOutputError包装的错误模板渲染随即失败避免静默降级进程内缓存以pass-name为 key 缓存原始输出map[string][]byte此后pass、passFields、passRaw对同一pass-name的调用都会直接命中缓存不再执行外部命令。对应的配置结构定义在同一文件中type passConfig struct { Command string json:command mapstructure:command yaml:command cache map[string][]byte }可见passConfig同时承载可配置的命令名Command支持 JSON / mapstructure / YAML 三种配置来源与进程内缓存字段。配置 pass 命令与使用 passage 等兼容客户端pass系列模板函数默认调用名为pass的二进制。如需切换到其他 pass 兼容客户端例如 passage可以通过配置pass.command完成。官方文档index.md给出的 TOML 示例[pass] command passage配置后pass、passFields、passRaw会改为执行passage show pass-name其余行为完全一致——这意味着你可以用 passage 管理密码库同时沿用 chezmoi 的整套pass*模板函数。对应的 YAML 配置写法为pass: command: passage默认值方面从 internal/cmd/config.go 可以看到Pass: passConfig{Command: pass}即未配置时命令名为pass。另外doctor命令会检查pass.command指定的二进制是否存在于PATH中——相关逻辑位于 internal/cmd/doctorcmd.go因此运行chezmoi doctor可以快速验证 pass 客户端是否就绪。测试验证txtar 集成测试如何背书chezmoi 的仓库为pass系列函数提供了可运行的集成测试位于 internal/cmd/testdata/scripts/pass.txtar。该测试使用mockcommand伪造了一个pass二进制其关键内容如下# test pass template function exec chezmoi execute-template {{ pass misc/example.com }} stdout ^examplepassword$ # test passFields template function exec chezmoi execute-template {{ (passFields misc/example.com).login }} stdout ^examplelogin$ # test pass template function exec chezmoi execute-template {{ passRaw misc/example.com }} cmp stdout golden/pass-raw配套的 mock 响应-- bin/pass.yaml --模拟了pass show misc/example.com的输出examplepassword login: examplelogin而 golden 文件golden/pass-raw期望passRaw输出完整的两行examplepassword login: examplelogin从该测试可以印证前面所有行为约定pass只返回第一行examplepasswordpassFields把第二行解析为login - examplelogin(passFields misc/example.com).login渲染为exampleloginpassRaw保留完整的两行原始输出与 golden 文件逐字节一致Windows 下先执行unix2dos转换以兼容换行符。测试执行方式与 chezmoi 其他 txtar 测试一致go test ./internal/cmd -run TestScript/pass一类命令具体入口可参考 internal/cmd/main_test.go它保证了三个函数在真实命令执行链路下的行为稳定。三个函数的选用建议结合官方文档与源码行为可以给出以下选型参考只需要密码本身使用pass例如{{ pass email/example }}需要条目中的附加字段login、URL、备注等使用passFields取结构化字段例如{{ (passFields email/example).login }}需要完整多行输出或原始格式使用passRaw例如把整段 SSH 密钥或证书内容写入模板同一 pass-name 被多处引用三个函数共享缓存只会触发一次pass show无需担心重复执行。使用前提与注意事项pass系列函数依赖本机已安装 pass 或兼容客户端如 passage且密码库能被当前用户正常解密访问通常需要 GPG key 或对应密钥命令未安装或执行失败时模板渲染会直接报错而非返回空值。敏感数据通过外部命令动态注入点文件仓库本身不保存明文但应避免将渲染产物如chezmoi apply生成的最终文件提交到不安全的仓库。渲染过程中若需跳过所有敏感数据skipSecrets场景三个函数都会经由chezmoi.SkipTemplateIf被跳过模板整体不会执行可用于 CI 等不应接触密钥的环境。【免费下载链接】chezmoiManage your dotfiles across multiple diverse machines, securely.项目地址: https://gitcode.com/gh_mirrors/ch/chezmoi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考