chezmoi source state, differences and synchronisation
On this page
chezmoi maintains source configuration and renders files for the current machine. Git records source history; chezmoi updates actual target files. A committed change has not necessarily been applied.
Understand three states
| State | Example | What changes it |
|---|---|---|
| Source | dot_wezterm.lua in the source directory | Editor, Git, add |
| Target | Desired rendered .wezterm.lua | chezmoi calculation |
| Actual | The file currently in the home directory | apply or direct editing |
chezmoi diff compares actual and desired target state. Direct target edits do not automatically update source state.
Add one working file
Assume .wezterm.lua exists and works. Initialise:
Add only this file:
Inspect its source location and differences:
Immediately after adding an unchanged file, there should normally be no target difference. No remote repository has been published; Git remotes and commits are separate steps.
Edit, review and apply
This edits the source. After saving, review:
Apply only after confirming the change:
Check diff again and verify the application accepts the configuration. An empty diff proves target consistency, not application correctness. Daily operations
Enter a shell in the source repository:
Run git status, select files and follow the Git handbook. Exit that shell when finished. chezmoi cd && git ... is not equivalent to a normal cd that permanently changes the parent shell's directory.
Express machine differences with templates
Edit the source with chezmoi edit. Within a complete WezTerm configuration, this fragment selects a Windows program:
{{ if eq .chezmoi.os "windows" }}
config.default_prog = { "pwsh.exe", "-NoLogo" }
{{ end }}
The surrounding config object and return belong to the WezTerm configuration. chezmoi data displays machine data and may contain personal settings; avoid posting the complete output publicly.
Use chezmoi cat ~/.wezterm.lua to inspect the rendered target, then validate the resulting Lua. Template validity and application-configuration validity are different checks.
Attributes and management boundaries
dot_ represents a dotfile, private_ restricts target permissions, executable_ adds execution permissions and .tmpl marks a template. private_ does not encrypt repository content. Source attributes
Manage handwritten settings that should agree across machines. Rebuild plugin caches, logs, generated themes and session databases through their tools. For a large third-party desktop shell, preserve upstream version and local patches instead of treating the whole installation tree as handwritten configuration.
Source scripts can execute during apply. Review scripts, templates and target scope before applying an unfamiliar repository; init --apply is not a review-free installation step.
Resolve changes from two machines
Preserve both actual configurations before fetching and merging source changes. chezmoi merge can reconcile target edits with source. Re-adding a file updates source state, so first decide which content should survive.
Git can restore old source files, but it does not automatically rewrite the home directory. After restoring source, review diff and apply to the intended target. Scripts may also have changed external state that file restoration cannot undo.
Practise adding, editing, previewing, applying and restoring an unimportant configuration. Identify which state changes at every step before relying on cross-machine synchronisation.