chezmoi 模板函数passRaw详解：读取 pass 密码库的完整原始内容
【免费下载链接】chezmoiManage your dotfiles across multiple diverse machines, securely.项目地址: https://gitcode.com/gh_mirrors/ch/chezmoi
导读
passRaw是 chezmoi 内置的一组 pass 模板函数之一，用于在生成点文件模板时读取 pass（Unix 密码管理器）中存储的密码条目。与仅返回首行的pass函数不同，passRaw将pass show的全部输出原样返回，适合读取多行结构的密码条目（如包含备注、多字段信息的完整记录）。读完本文，你将掌握passRaw的调用语法、与pass/passFields的差异、底层缓存机制，以及如何通过pass.command配置接入 passage 等 pass 兼容工具。
函数签名与核心语义
passRaw的模板调用形式为：
{{ passRaw "<pass-name>" }}根据 passRaw 参考文档 的定义：
passRaw使用 pass 命令行工具（pass）返回存储在 pass 中的密码；- 模板参数pass-name会被原样拼接到
pass show $PASS_NAME命令中执行； pass命令的完整输出被直接返回——不做首行截断、不做字段解析；- 输出结果会被缓存：同一pass-name多次调用
passRaw时，pass进程只会在第一次真正执行。
这与 chezmoi 中另外两个 pass 函数形成互补：
| 模板函数 | 返回内容 | 适用场景 |
|---|---|---|
pass | pass show输出的第一行，去掉末尾换行符 | 常规密码（单行口令） |
passFields | 按行解析key: value冒号分隔结构，返回键值映射 | 结构化元数据（登录名、URL 等） |
passRaw | pass show的完整原始输出 | 多行备注、证书、密钥块等完整条目 |
三者共享同一底层调用与缓存，但输出处理策略各不相同，详见下文源码分析。
与pass/passFields的行为差异
pass函数会截取pass show输出的第一行并去除行尾空白。例如对如下 pass 条目：
examplepassword login: examplelogin{{ pass "misc/example.com" }}返回examplepassword；{{ (passFields "misc/example.com").login }}返回examplelogin；{{ passRaw "misc/example.com" }}返回完整两行文本：
examplepassword login: examplelogin因此，当你的密码条目只有单行口令时，pass与passRaw结果等价；但当条目包含多行附加信息（TOTP 密钥、SSH 私钥、多字段记录等），需要完整内容时就必须使用passRaw。相关函数的行为说明分别见 pass 参考文档 与 passFields 参考文档。
源码级实现原理
passRaw的实际实现位于 internal/cmd/passtemplatefuncs.go，核心逻辑如下：
func (c *Config) passRawTemplateFunc(id string) string { chezmoi.SkipTemplateIf(c.skipSecrets) return string(mustValue(c.passOutput(id))) }从源码结构可以归纳出以下几点实现事实：
- 跳过标记：函数首先调用
chezmoi.SkipTemplateIf(c.skipSecrets)。当用户设置了跳过机密（secrets）的相关配置时，模板渲染会被提前中断，避免在不应读取机密的场景下触发pass外部调用。 - 完整输出：
passRaw直接返回passOutput的字节内容并转换为字符串，不做任何首行截断或字段解析——这正是它与pass（bytes.Cut(output, []byte{'\n'})截首行）、passFields（按:切分键值）在源码层面的本质区别。 - 命令拼接：底层
passOutput通过exec.Command(c.Pass.Command, "show", id)构造命令，等效于 shell 中的pass show $PASS_NAME，同时将标准输入与标准错误透传给终端，确保 GPG 解密时的交互提示（如 PIN 输入）能够正常进行。 - 错误处理：命令执行失败时，
passOutput返回newCmdOutputError包装的错误，mustValue会将其转换为模板渲染错误，最终导致chezmoi execute-template等命令以非零状态退出。
缓存机制：一次调用，多次复用
passOutput实现了按条目 ID 的进程级缓存：
func (c *Config) passOutput(id string) ([]byte, error) { if output, ok := c.Pass.cache[id]; ok { return output, nil } // ... 执行 pass show $ID ... c.Pass.cache[id] = output return output, nil }passConfig结构体（同文件）包含Command string与cache map[string][]byte两个字段，缓存以pass-name为键。这意味着：在一次chezmoi apply、chezmoi execute-template等命令的运行过程中，如果多个模板文件引用了同一个 pass 条目，pass进程只会真正执行一次，其余调用直接命中缓存——既节省了外部进程开销，也减少了 GPG 解密次数。
配置 pass 命令与兼容工具
passRaw及其他 pass* 函数默认调用二进制名为pass的命令。从 internal/cmd/config.go 可以看到默认配置：
Pass: passConfig{ Command: "pass", },该配置可在 chezmoi 配置文件中通过pass.command覆盖。一个典型场景是接入 pass 的兼容实现 passage 中给出了 TOML 示例：
[pass] command = "passage"设置后，passRaw、pass、passFields三个函数都会透明地改用passage二进制，模板代码无需任何改动。命令格式同样支持其他配置格式（如 JSON/YAML），字段名均为pass.command。
实战用法示例
读取完整多行条目
# 假设 pass 条目 misc/example.com 内容为： # examplepassword # login: examplelogin {{ passRaw "misc/example.com" }}渲染结果为：
examplepassword login: examplelogin结合字符串处理提取子内容
由于返回的是完整文本，你可以继续用 sprig 等模板函数做二次处理，例如只取第一行：
{{ (passRaw "misc/example.com" | splitList "\n" | first) }}在点文件模板中的典型用法
以管理包含完整私钥内容的文件为例，passRaw可以直接作为文件内容注入：
# ~/.local/share/chezmoi/private_dot_ssh/private_id_ed25519.tmpl {{ passRaw "ssh/ed25519" }}测试验证
仓库中的 pass.txtar 集成测试 使用 mock 的pass二进制验证了三个函数的完整行为：
exec chezmoi execute-template '{{ pass "misc/example.com" }}' stdout ^examplepassword$ exec chezmoi execute-template '{{ (passFields "misc/example.com").login }}' stdout ^examplelogin$ exec chezmoi execute-template '{{ passRaw "misc/example.com" }}' cmp stdout golden/pass-raw其中 mockpass对show misc/example.com返回如下内容，而 golden 文件golden/pass-raw中保存的正是完整输出（两行均包含）：
examplepassword login: examplelogin这从测试角度印证了本文的关键结论：pass只取首行、passFields解析键值、passRaw原样返回全部输出。该测试同时验证了缓存逻辑——三次调用同一条目，mock 的pass只被触发一次。
小结
passRaw返回pass show <name>的完整原始输出，适合多行结构的密码条目；- 同一进程内对同一条目的多次调用只执行一次
pass（缓存机制）； - 默认使用
pass二进制，可通过pass.command切换为 passage 等兼容工具； - 与
pass（首行）、passFields（键值映射）共同构成 chezmoi 的 pass 模板函数族，可在 用户指南 与 pass-functions 参考目录 中查看更多资料。
【免费下载链接】chezmoiManage your dotfiles across multiple diverse machines, securely.项目地址: https://gitcode.com/gh_mirrors/ch/chezmoi
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
