Skip to main content

​
Understand chezmoi’s files and directories

chezmoi generates your dotfiles for your local machine by combining two main sources of data: Source directory (~/.local/share/chezmoi)
  • Common to all your machines
  • A clone of your dotfiles repo
  • Each managed file has a corresponding source file here
Config file (~/.config/chezmoi/chezmoi.toml)
  • Specific to the local machine
  • Can also use JSON or YAML format
  • Contains machine-specific variables
Files with identical contents across machines are copied verbatim. Files that vary are executed as templates, using data from the config file to customize content for each machine.

​
Use a hosted repo to manage your dotfiles across multiple machines

chezmoi uses version control to share changes across machines. You should create a repo on your preferred platform (GitHub, GitLab, Bitbucket) to store your dotfiles.
1

Push your dotfiles to a remote repo

Navigate to your source directory and add a remote:
chezmoi cd
git remote add origin https://github.com/$GITHUB_USERNAME/dotfiles.git
git push -u origin main
exit
2

Initialize chezmoi on another machine

Clone your dotfiles repo:
chezmoi init https://github.com/$GITHUB_USERNAME/dotfiles.git
3

Preview and apply changes

See what would be changed:
chezmoi diff

​
Use a private repo to store your dotfiles

chezmoi supports both public and private repos. For security:
  • Store secrets in password managers or encrypted files
  • Keep private data in machine-specific config files
  • Your dotfiles repo can remain public
When using a private GitHub repo without SSH, you’ll need to use a GitHub personal access token instead of your password.

​
Create a config file on a new machine automatically

Automate config file creation by adding a .chezmoi.toml.tmpl template to your repo: 
{{- $email := promptStringOnce . "email" "Email address" -}}

[data]
    email = {{ $email | quote }}
When you run chezmoi init, this template will generate your chezmoi.toml config file. The promptStringOnce function prompts for values not already set.
1

Test the template

Use execute-template to test without creating files:
chezmoi execute-template --init --promptString "Email [email protected]" < ~/.local/share/chezmoi/.chezmoi.toml.tmpl
2

Re-create your config file

If you update the template, regenerate your config:
chezmoi init
Using promptStringOnce prevents re-prompting for existing values.
Supported config formats: json, jsonc, toml, and yaml. Name your template .chezmoi.$FORMAT.tmpl.

Build docs developers (and LLMs) love

Get started for freeTalk to us