Back to Details

chezmoi-config

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Chezmoi Configuration Management

Chezmoi配置文件管理

Comprehensive guide for managing chezmoi dotfiles with templates, scripts, external resources, and advanced configurations.
使用模板、脚本、外部资源和高级配置管理chezmoi配置文件的全面指南。

⚠️ Safety Constraints

⚠️ 安全约束

This skill is READ-ONLY and validation-only. It MUST NOT modify your actual environment.
本技能仅支持只读和验证操作，绝对不能修改你的实际环境。

Forbidden Operations

禁止操作

NEVER execute these commands - they will modify your system:
  • chezmoi apply
    - Applies changes to your home directory
  • chezmoi apply --force
    - Forcefully applies changes
  • chezmoi update
    - Updates source state and may change managed files
  • Any operations that directly execute scripts (scripts run automatically during 
    chezmoi apply
    )
绝不要执行以下命令——它们会修改你的系统：
  • chezmoi apply
    - 将变更应用到你的主目录
  • chezmoi apply --force
    - 强制应用变更
  • chezmoi update
    - 更新源状态并可能修改受管文件
  • 任何直接执行脚本的操作（脚本会在
    chezmoi apply
    期间自动运行）

Allowed Safe Operations

允许的安全操作

ONLY use these read-only validation commands:
  • chezmoi diff
    - Preview what would change (safe)
  • chezmoi apply --dry-run
    - Simulate changes without applying (safe)
  • chezmoi doctor
    - Check configuration validity (safe)
  • chezmoi data
    - Display template data variables (safe)
  • chezmoi managed
    - List files currently managed by chezmoi (read-only, safe)
  • chezmoi unmanaged
    - List files currently unmanaged by chezmoi (read-only, safe)
  • chezmoi ignored
    - List files ignored by chezmoi (read-only, safe)
  • chezmoi execute-template < file.tmpl
    - Preview expanded template output (safe)
  • chezmoi state dump
    - View script execution state (safe)
  • chezmoi verify
    - Verify source state integrity (safe)
  • chezmoi cd
    - Enter source directory (safe)
  • chezmoi source-path
    - Show source directory path (safe)
仅可使用以下只读验证命令：
  • 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
    - 显示源目录路径（安全）

User Responsibility

用户责任

This skill helps you create and validate chezmoi configurations. To apply changes, you must manually run 
chezmoi apply
in your terminal after reviewing the output.
本技能帮助你创建和验证chezmoi配置。若要应用变更，你必须在查看输出后手动在终端中运行
chezmoi apply
。

Quick Start

快速入门

Creating a New Template

创建新模板

  1. Add existing file as template:
    bash
    chezmoi add --template ~/.gitconfig
  2. Or create manually:
    bash
    chezmoi cd
$EDITOR dot_gitconfig.tmpl
  3. Use Go template syntax:
    go
    [user]
    name = {{ .name }}
{{- if eq .chezmoi.os "darwin" }}
[credential]
    helper = osxkeychain
{{- end }}
  1. 将现有文件添加为模板：
    bash
    chezmoi add --template ~/.gitconfig
  2. 或手动创建：
    bash
    chezmoi cd
$EDITOR dot_gitconfig.tmpl
  3. 使用Go模板语法：
    go
    [user]
    name = {{ .name }}
{{- if eq .chezmoi.os "darwin" }}
[credential]
    helper = osxkeychain
{{- end }}

Managing External Resources

管理外部资源

Create 
.chezmoiexternal.toml.tmpl
:
toml
[".oh-my-zsh"]
    type = "archive"
    url = "https://github.com/ohmyzsh/ohmyzsh/archive/master.tar.gz"
    exact = true
    stripComponents = 1
创建
.chezmoiexternal.toml.tmpl
：
toml
[".oh-my-zsh"]
    type = "archive"
    url = "https://github.com/ohmyzsh/ohmyzsh/archive/master.tar.gz"
    exact = true
    stripComponents = 1

Writing Scripts

编写脚本

Create 
run_onchange_install-packages.sh.tmpl
:
bash
{{ if eq .chezmoi.os "darwin" -}}
#!/bin/bash
brew install git vim ripgrep
{{ end -}}
创建
run_onchange_install-packages.sh.tmpl
：
bash
{{ if eq .chezmoi.os "darwin" -}}
#!/bin/bash
brew install git vim ripgrep
{{ end -}}

Reference Documentation

参考文档

This skill includes comprehensive reference documentation. Consult these guides for detailed information:
  • template-syntax.md - Go template syntax, variables, conditionals, loops, and examples
  • external-files.md - .chezmoiexternal configuration for files, archives, and git repositories
  • ignore-files.md - .chezmoiignore/.chezmoiignore.tmpl patterns, templates, and scope
  • password-managers.md - Integrating 20+ password managers (1Password, Bitwarden, Vault, etc.)
  • scripts.md - run_once, run_onchange, run_before, run_after scripts
  • advanced-configuration.md - .chezmoi.toml, prompting, encryption, and advanced features
本技能包含完整的参考文档。如需详细信息，请查阅以下指南：
  • 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、交互式提示、加密及高级功能

Common Tasks

常见任务

1. Create Platform-Specific Configuration

1. 创建平台专属配置

Template file (dot_gitconfig.tmpl):
go
[user]
    name = {{ .name }}
    email = {{ .email }}

{{- if eq .chezmoi.os "darwin" }}
[credential]
    helper = osxkeychain
{{- else if eq .chezmoi.os "linux" }}
[credential]
    helper = cache
{{- end }}
Configuration (chezmoi.toml):
toml
[data]
    name = "John Doe"
    email = "john@example.com"
模板文件（dot_gitconfig.tmpl）：
go
[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）：
toml
[data]
    name = "John Doe"
    email = "john@example.com"

2. Manage Secrets with Password Managers

2. 使用密码管理器管理敏感信息

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

3. Install Packages Conditionally

3. 条件化安装软件包

run_onchange_install-packages.sh.tmpl:
bash
{{ 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:
yaml
darwin:
  brews:
    - git
    - vim
    - ripgrep

linux:
  - git
  - vim
  - ripgrep
  - fd-find
run_onchange_install-packages.sh.tmpl：
bash
{{ 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：
yaml
darwin:
  brews:
    - git
    - vim
    - ripgrep

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

4. Include External Resources

4. 引入外部资源

.chezmoiexternal.toml.tmpl:
toml
[".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
.chezmoiexternal.toml.tmpl：
toml
[".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. Configure Interactive Prompts

5. 配置交互式提示

.chezmoi.toml.tmpl:
toml
{{- $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 }}
.chezmoi.toml.tmpl：
toml
{{- $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. Ignore Files Conditionally

6. 条件化忽略文件

.chezmoiignore (template-aware):
text
README.md
*.log

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

{{- if eq .chezmoi.os "windows" }}
Documents/*
!Documents/*PowerShell/
{{- end }}
.chezmoiignore（支持模板）：
text
README.md
*.log

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

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

7. Interpret 
chezmoi managed
/ 
chezmoi unmanaged
Output (Config Files)

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

When reviewing 
chezmoi unmanaged
, note that the destination config file is 
~/.config/chezmoi/chezmoi.toml
, while the source is typically managed as a template such as 
dot_config/chezmoi/chezmoi.toml.tmpl
(or 
private_dot_config/chezmoi/chezmoi.toml.tmpl
) in the chezmoi source state.
If 
~/.config/chezmoi
appears as unmanaged:
  • First check 
    chezmoi managed
    to confirm whether the config file is already managed in source.
  • If it is not managed, add it as a template and manage it in source (recommended when you maintain machine-specific values in 
    chezmoi.toml
    ).
查看
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. Manage run_once Scripts

8. 管理run_once脚本

run_once_000-bootstrap.sh.tmpl:
bash
#!/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 -}}
Reset run_once state:
bash
undefined
run_once_000-bootstrap.sh.tmpl：
bash
#!/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状态：
bash
undefined

Clear all run_once script state

清除所有run_once脚本状态

chezmoi state delete-bucket --bucket=scriptState
undefined
chezmoi state delete-bucket --bucket=scriptState
undefined

Built-in Variables

内置变量

Commonly used chezmoi variables available in all templates:
VariableDescriptionExample
.chezmoi.os
Operating system
linux
, 
darwin
, 
windows
.chezmoi.arch
Architecture
amd64
, 
arm64
.chezmoi.hostname
Machine hostname
my-laptop
.chezmoi.username
Current user
john
.chezmoi.homeDir
Home directory
/home/john
.chezmoi.sourceDir
Source state directory
/home/john/.local/share/chezmoi
.chezmoi.env.VAR
Environment variables
.chezmoi.env.EDITOR
所有模板中均可使用的常用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

Template Syntax Reference

模板语法参考

Conditionals

条件语句

go
{{ if eq .chezmoi.os "darwin" }}
go
{{ if eq .chezmoi.os "darwin" }}

macOS-specific

macOS专属配置

{{ else if eq .chezmoi.os "linux" }}
{{ else if eq .chezmoi.os "linux" }}

Linux-specific

Linux专属配置

{{ end }}
undefined
{{ end }}
undefined

Loops

循环语句

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

String Operations

字符串操作

go
{{ .name | quote }}          # Add quotes
{{ .chezmoi.homeDir }}        # No trimming
{{- "content" -}}            # Trim whitespace
go
{{ .name | quote }}          # 添加引号
{{ .chezmoi.homeDir }}        # 不修剪空格
{{- "content" -}}            # 修剪空格

Best Practices

最佳实践

  1. Use templates for cross-platform configs - Leverage 
    .chezmoi.os
    , 
    .chezmoi.arch
  2. Store secrets in password managers - Never hardcode sensitive data
  3. Make scripts idempotent - Safe to run multiple times
  4. Use descriptive filenames - 
    run_once_000-bootstrap.sh.tmpl
  5. Test templates locally - Use 
    chezmoi execute-template < file.tmpl
  6. Organize .chezmoidata - Separate concerns into multiple files
  7. Document dependencies - Comment complex configurations
  8. Use appropriate refresh periods - Balance freshness and bandwidth
  1. 使用模板实现跨平台配置 - 利用
    .chezmoi.os
    、
    .chezmoi.arch
    变量
  2. 将敏感信息存储在密码管理器中 - 绝不硬编码敏感数据
  3. 确保脚本具有幂等性 - 可安全多次运行
  4. 使用描述性文件名 - 例如
    run_once_000-bootstrap.sh.tmpl
  5. 本地测试模板 - 使用
    chezmoi execute-template < file.tmpl
  6. 组织.chezmoidata文件 - 将不同关注点拆分到多个文件中
  7. 记录依赖关系 - 为复杂配置添加注释
  8. 设置合适的刷新周期 - 在新鲜度和带宽之间取得平衡

Consulting Latest Documentation

查阅最新文档

This skill can consult the latest chezmoi documentation via Context7 to ensure accuracy:
bash
undefined
本技能可通过Context7查阅最新的chezmoi文档，确保信息准确性：
bash
undefined

When in doubt, ask for the latest docs

如有疑问，请求取最新文档

"Check the chezmoi documentation for [topic]"

If the question involves `.tmpl` behavior (especially `.chezmoiignore{,.tmpl}`), prefer checking the official docs first.
"查阅chezmoi关于[主题]的文档"

若问题涉及`.tmpl`的行为（尤其是`.chezmoiignore{,.tmpl}`），建议优先查阅官方文档。

Useful Commands

实用命令

bash
undefined
bash
undefined

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

⚠️ 禁止操作 - 应用所有变更（必须手动运行）

chezmoi apply
chezmoi apply

Dry run (preview changes) - SAFE

试运行（预览变更）- 安全

chezmoi apply --dry-run
chezmoi apply --dry-run

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

⚠️ 禁止操作 - 更新源状态（可能修改受管文件）

chezmoi update
chezmoi update

Edit source state - SAFE

编辑源状态 - 安全

chezmoi cd
chezmoi cd

Add file as template - SAFE

将文件添加为模板 - 安全

chezmoi add --template ~/.config/file
chezmoi add --template ~/.config/file

Verify configuration - SAFE

验证配置 - 安全

chezmoi doctor
chezmoi doctor

View all template data - SAFE

查看所有模板数据 - 安全

chezmoi data
chezmoi data

List ignored files - SAFE

列出被忽略的文件 - 安全

chezmoi ignored
chezmoi ignored

Test template (preview output) - SAFE

测试模板（预览输出）- 安全

chezmoi execute-template < ~/.local/share/chezmoi/dot_file.tmpl
chezmoi execute-template < ~/.local/share/chezmoi/dot_file.tmpl

View run_once state - SAFE

查看run_once状态 - 安全

chezmoi state dump
chezmoi state dump

Clear run_once script state (use with caution) - SAFE

清除run_once脚本状态（谨慎使用）- 安全

chezmoi state delete-bucket --bucket=scriptState
chezmoi state delete-bucket --bucket=scriptState

Clear run_onchange script state (use with caution) - SAFE

清除run_onchange脚本状态（谨慎使用）- 安全

chezmoi state delete-bucket --bucket=entryState
chezmoi state delete-bucket --bucket=entryState

See what would change - SAFE

查看将会发生的变更 - 安全

chezmoi diff
chezmoi diff

Verify files match expected state - SAFE

验证文件是否符合预期状态 - 安全

chezmoi verify
undefined
chezmoi verify
undefined

File Structure

文件结构

Standard chezmoi source state structure:
~/.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源状态结构：
~/.local/share/chezmoi/
├── .chezmoi.toml.tmpl          # 主配置（可选）
├── .chezmoiexternal.toml.tmpl   # 外部资源（可选）
├── .chezmoiignore.tmpl          # 忽略规则（支持模板，可选）
├── .chezmoidata/
│   ├── packages.yaml            # 自定义数据
│   └── work.yaml
├── dot_gitconfig.tmpl           # 常规模板
├── dot_zshrc.tmpl
├── run_once_000-bootstrap.sh.tmpl
├── run_onchange_install-packages.sh.tmpl
└── run_after_dot_vimrc.sh.tmpl

Debugging

调试

注意：调试时也不要执行 
chezmoi update
，如需检查变更请用 
chezmoi diff
或 
chezmoi apply --dry-run
。
Verbose output:
bash
chezmoi apply --verbose
Check what would change:
bash
chezmoi diff
Validate configuration:
bash
chezmoi doctor
See expanded template:
bash
chezmoi execute-template < template-file
注意：调试时也不要执行
chezmoi update
，如需检查变更请使用
chezmoi diff
或
chezmoi apply --dry-run
。
详细输出：
bash
chezmoi apply --verbose
查看将会发生的变更：
bash
chezmoi diff
验证配置：
bash
chezmoi doctor
查看展开后的模板：
bash
chezmoi execute-template < template-file

When to Use This Skill

何时使用本技能

Use this skill whenever you're:
  • Creating new chezmoi templates with Go syntax
  • Modifying existing .chezmoi configuration files
  • Managing .chezmoiignore/.chezmoiignore.tmpl rules
  • Setting up .chezmoiexternal for external resources
  • Writing run_once/run_onchange scripts
  • Integrating password managers for secrets
  • Managing cross-platform dotfiles
  • Debugging template issues
  • Organizing .chezmoidata files
For specific concerns, refer to the detailed reference documentation listed above.
在以下场景中使用本技能：
  • 使用Go语法创建新的chezmoi模板
  • 修改现有chezmoi配置文件
  • 管理.chezmoiignore/.chezmoiignore.tmpl规则
  • 配置.chezmoiexternal以管理外部资源
  • 编写run_once/run_onchange脚本
  • 集成密码管理器处理敏感信息
  • 管理跨平台配置文件
  • 调试模板问题
  • 组织.chezmoidata文件
如需特定问题的帮助，请参考上述详细参考文档。",