chezmoi-config

Chezmoi 配置管理

使用模板、脚本、外部资源和高级配置管理 chezmoi 点文件的综合指南。

⚠️ 安全限制

此技能为只读且仅用于验证。绝不能修改你的实际环境。

禁止的操作

切勿执行以下命令——它们会修改你的系统：

• chezmoi apply - 将更改应用到你的主目录
• chezmoi apply --force - 强制应用更改
• chezmoi update - 更新源状态，并可能更改受管理的文件
• 任何直接执行脚本的操作（脚本会在 chezmoi apply 期间自动运行）

允许的安全操作

仅使用以下只读验证命令：

• chezmoi diff - 预览将要发生的更改（安全）
• chezmoi apply --dry-run - 模拟更改但不应用（安全）
• chezmoi doctor - 检查配置是否有效（安全）
• chezmoi data - 显示模板数据变量（安全）
• chezmoi managed - 列出当前由 chezmoi 管理的文件（只读、安全）
• chezmoi unmanaged - 列出当前未由 chezmoi 管理的文件（只读、安全）
• chezmoi ignored - 列出 chezmoi 忽略的文件（只读、安全）
• chezmoi execute-template < file.tmpl - 预览展开后的模板输出（安全）
• chezmoi state dump - 查看脚本执行状态（安全）
• chezmoi verify - 验证源状态完整性（安全）
• chezmoi cd - 进入源目录（安全）
• chezmoi source-path - 显示源目录路径（安全）

用户责任

此技能可帮助你创建和验证 chezmoi 配置。要应用更改，你必须在查看输出后，手动在终端中运行 chezmoi apply。

快速入门

创建新模板

1. 将现有文件添加为模板：

   chezmoi add --template ~/.gitconfig
   

2. 或者手动创建：

   chezmoi cd
   $EDITOR dot_gitconfig.tmpl
   

3. 使用 Go 模板语法：

   [user]
       name = {{ .name }}
   {{- if eq .chezmoi.os "darwin" }}
   [credential]
       helper = osxkeychain
   {{- end }}
   

管理外部资源

创建 .chezmoiexternal.toml.tmpl：

[".oh-my-zsh"]
    type = "archive"
    url = "https://github.com/ohmyzsh/ohmyzsh/archive/master.tar.gz"
    exact = true
    stripComponents = 1

编写脚本

创建 run_onchange_install-packages.sh.tmpl：

{{ if eq .chezmoi.os "darwin" -}}
#!/bin/bash
brew install git vim ripgrep
{{ end -}}

参考文档

此技能包含全面的参考文档。有关详细信息，请参阅以下指南：

• template-syntax.md - Go 模板语法、变量、条件语句、循环和示例
• external-files.md - 用于管理文件、归档和 Git 仓库的 .chezmoiexternal 配置
• ignore-files.md - .chezmoiignore/.chezmoiignore.tmpl 模式、模板和作用范围
• password-managers.md - 集成 20 多种密码管理器（1Password、Bitwarden、Vault 等）
• scripts.md - run_once、run_onchange、run_before、run_after 脚本
• advanced-configuration.md - .chezmoi.toml、提示、加密和高级功能

常见任务

1. 创建特定于平台的配置

模板文件（dot_gitconfig.tmpl）：

[user]
    name = {{ .name }}
    email = {{ .email }}

{{- if eq .chezmoi.os "darwin" }}
[credential]
    helper = osxkeychain
{{- else if eq .chezmoi.os "linux" }}
[credential]
    helper = cache
{{- end }}

配置（chezmoi.toml）：

[data]
    name = "John Doe"
    email = "[email protected]"

2. 使用密码管理器管理机密

{{- if (bitwarden "github") }}
[github]
    token = {{ (bitwarden "github").login.password }}
{{- end }}

3. 按条件安装软件包

run_onchange_install-packages.sh.tmpl：

{{ if eq .chezmoi.os "darwin" -}}
#!/bin/bash
brew bundle --file=/dev/stdin <<EOF
{{ range .packages.darwin.brews -}}
brew "{{ . }}"
{{ end -}}
EOF
{{ else if eq .chezmoi.os "linux" -}}
#!/bin/bash
sudo apt install -y {{ range .packages.linux }}{{ . }} {{ end }}
{{ end -}}

.chezmoidata/packages.yaml：

darwin:
  brews:
    - git
    - vim
    - ripgrep

linux:
  - git
  - vim
  - ripgrep
  - fd-find

4. 包含外部资源

.chezmoiexternal.toml.tmpl：

[".vim/autoload/plug.vim"]
    type = "file"
    url = "https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim"

[".oh-my-zsh"]
    type = "archive"
    url = "https://github.com/ohmyzsh/ohmyzsh/archive/master.tar.gz"
    exact = true
    stripComponents = 1
    refreshPeriod = "168h"

[".local/bin/age"]
    type = "archive-file"
    url = "https://github.com/FiloSottile/age/releases/download/v1.1.1/age-v1.1.1-{{ .chezmoi.os }}-{{ .chezmoi.arch }}.tar.gz"
    path = "age/age"
    executable = true

5. 配置交互式提示

.chezmoi.toml.tmpl：

{{- $editor := promptChoice "favorite editor" ["vim" "neovim" "vscode"] -}}
[data]
    name = "{{ promptString "your name" }}"
    email = "{{ promptString "your email" }}"
    editor = {{ $editor }}

{{ if promptBool "enable work config?" -}}
[data.work]
    enabled = true
    work_email = "{{ promptString "work email" }}"
{{ end }}

6. 按条件忽略文件

.chezmoiignore（支持模板）：

README.md
*.log

{{- if ne .chezmoi.hostname "work-laptop" }}
.work
{{- end }}

{{- if eq .chezmoi.os "windows" }}
Documents/*
!Documents/*PowerShell/
{{- end }}

7. 解读 chezmoi managed / chezmoi unmanaged 输出（配置文件）

查看 chezmoi unmanaged 时，请注意，目标配置文件是 ~/.config/chezmoi/chezmoi.toml，而源文件通常作为模板在 chezmoi 源状态中管理，例如 dot_config/chezmoi/chezmoi.toml.tmpl（或 private_dot_config/chezmoi/chezmoi.toml.tmpl）。

如果 ~/.config/chezmoi 显示为未管理：

• 首先检查 chezmoi managed，确认配置文件是否已在源状态中管理。
• 如果尚未管理，请将其添加为模板并纳入源状态管理（如果你会在 chezmoi.toml 中维护特定于机器的值，建议这样做）。

8. 管理 run_once 脚本

run_once_000-bootstrap.sh.tmpl：

#!/bin/bash
{{ if eq .chezmoi.os "darwin" -}}
if ! command -v brew &> /dev/null; then
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
fi
{{ end -}}

重置 run_once 状态：

# Clear all run_once script state
chezmoi state delete-bucket --bucket=scriptState

内置变量

所有模板中都可使用的常用 chezmoi 变量：

变量	说明	示例
.chezmoi.os	操作系统	linux、darwin、windows
.chezmoi.arch	架构	amd64、arm64
.chezmoi.hostname	机器主机名	my-laptop
.chezmoi.username	当前用户	john
.chezmoi.homeDir	主目录	/home/john
.chezmoi.sourceDir	源状态目录	/home/john/.local/share/chezmoi
.chezmoi.env.VAR	环境变量	.chezmoi.env.EDITOR

模板语法参考

条件语句

{{ if eq .chezmoi.os "darwin" }}
# macOS-specific
{{ else if eq .chezmoi.os "linux" }}
# Linux-specific
{{ end }}

循环

{{ range .packages.darwin.brews -}}
brew "{{ . }}"
{{ end -}}

字符串操作

{{ .name | quote }}          # Add quotes
{{ .chezmoi.homeDir }}        # No trimming
{{- "content" -}}            # Trim whitespace

最佳实践

1. 使用模板编写跨平台配置 - 利用 .chezmoi.os、.chezmoi.arch
2. 将密钥存储在密码管理器中 - 切勿将敏感数据硬编码
3. 让脚本具备幂等性 - 确保可安全地多次运行
4. 使用描述性文件名 - run_once_000-bootstrap.sh.tmpl
5. 在本地测试模板 - 使用 chezmoi execute-template < file.tmpl
6. 整理 .chezmoidata - 将不同关注点拆分到多个文件中
7. 记录依赖项 - 为复杂配置添加注释
8. 使用适当的刷新周期 - 平衡新鲜度与带宽

查阅最新文档

此技能可通过 Context7 查阅最新的 chezmoi 文档，以确保准确性：

# When in doubt, ask for the latest docs
"Check the chezmoi documentation for [topic]"

如果问题涉及 .tmpl 行为（尤其是 .chezmoiignore{,.tmpl}），请优先查阅官方文档。

有用的命令

# ⚠️ FORBIDDEN - Apply all changes (must run manually)
chezmoi apply

# Dry run (preview changes) - SAFE
chezmoi apply --dry-run

# ⚠️ FORBIDDEN - Update source state (may change managed files)
chezmoi update

# Edit source state - SAFE
chezmoi cd

# Add file as template - SAFE
chezmoi add --template ~/.config/file

# Verify configuration - SAFE
chezmoi doctor

# View all template data - SAFE
chezmoi data

# List ignored files - SAFE
chezmoi ignored

# Test template (preview output) - SAFE
chezmoi execute-template < ~/.local/share/chezmoi/dot_file.tmpl

# View run_once state - SAFE
chezmoi state dump

# Clear run_once script state (use with caution) - SAFE
chezmoi state delete-bucket --bucket=scriptState

# Clear run_onchange script state (use with caution) - SAFE
chezmoi state delete-bucket --bucket=entryState

# See what would change - SAFE
chezmoi diff

# Verify files match expected state - SAFE
chezmoi verify

文件结构

标准 chezmoi 源状态结构：

~/.local/share/chezmoi/
├── .chezmoi.toml.tmpl          # Main configuration (optional)
├── .chezmoiexternal.toml.tmpl   # External resources (optional)
├── .chezmoiignore.tmpl          # Ignore rules (template-aware, optional)
├── .chezmoidata/
│   ├── packages.yaml            # Custom data
│   └── work.yaml
├── dot_gitconfig.tmpl           # Regular templates
├── dot_zshrc.tmpl
├── run_once_000-bootstrap.sh.tmpl
├── run_onchange_install-packages.sh.tmpl
└── run_after_dot_vimrc.sh.tmpl

调试

注意：调试时也不要执行 chezmoi update，如需检查变更请用 chezmoi diff 或 chezmoi apply --dry-run。

详细输出：

chezmoi apply --verbose

检查将发生的变更：

chezmoi diff

验证配置：

chezmoi doctor

查看展开后的模板：

chezmoi execute-template < template-file

何时使用此技能

在以下情况下使用此技能：

• 使用 Go 语法创建新的 chezmoi 模板
• 修改现有的 .chezmoi 配置文件
• 管理 .chezmoiignore/.chezmoiignore.tmpl 规则
• 设置 .chezmoiexternal 以使用外部资源
• 编写 run_once/run_onchange 脚本
• 集成密码管理器以管理密钥
• 管理跨平台点文件
• 调试模板问题
• 整理 .chezmoidata 文件

如需了解具体问题，请参阅上文列出的详细参考文档。