Skip to content

This document is a WORK IN PROGRESS.
This is just a quick personal cheat sheet: treat its contents with caution!


chezmoi helps you manage your personal configuration files (dotfiles, like ~/.gitconfig) across multiple machines.

chezmoi provides many features beyond symlinking or using a bare git repo including: templates (to handle small differences between machines), password manager support (to store your secrets securely), importing files from archives (great for shell and editor plugins), full file encryption (using gpg or age), and running scripts (to handle everything else).


Table of contents


# apk add chezmoi




# nix-env -iA nixos.chezmoi
# nix-env -iA nixpkgs.chezmoi
# pacman -S chezmoi


# xbps-install -S chezmoi
# zypper install chezmoi


  • Initialize chezmoi:

    $ chezmoi init
  • Create yourself a dedicated dotfile repository on a Git server, and link your local chezmoi to it:

    $ chezmoi cd  # change directory to `$HOME/.local/share/chezmoi`
    $ git add .
    $ git commit -m "initial commit"
    $ git remote add origin$USERNAME/dotfiles.git
    $ git branch -M main
    $ git push -u origin main
    $ exit


  • Get help if needed:

    $ chezmoi help
  • Check common problems. If you encounter something unexpected, run this first.

    $ chezmoi doctor
  • Add dotfiles:

    $ chezmoi add $HOME/path/to/any/dotfile
  • Edit dotfiles with chezmoi (you have 4 different options for doing it):

    1. Use $ chezmoi edit $FILE. This will open the source file for $FILE in your editor. Optionally, you can use $ chezmoi edit --apply $FILE to apply the changes when you quit your editor,

    2. Use chezmoi cd and edit the files in the source directory directly. Then run $ chezmoi apply to make the changes.

    3. Edit the file in your home directory, and then either re-add it by running $ chezmoi add $FILE or $ chezmoi re-add.

    4. Edit the file in your home directory, and then merge your changes with source state by running $ chezmoi merge $FILE (invoking a merge tool, by default vimdiff)

  • Show a quick summary of what files would change if you ran chezmoi apply:

    $ chezmoi status
  • Shows changes that $ chezmoi apply would make to your home directory:

    $ chezmoi diff
  • Apply changes locally (i.e. apply what's in $HOME/.local/share/chezmoi to your local dotfiles):

    $ chezmoi apply -v
  • Automatically apply changes whenever a file is saved (after editing the file with chezmoi):

    $ chezmoi edit --watch $FILE`

Working across multiple machines

  • Initialize chezmoi from another machine with your dotfiles repository:

    $ chezmoi init$USERNAME/dotfiles.git

    (then, just apply changes locally)

  • Initialize chezmoi and apply changes from another machine with your dorfile repository, in a single command:

    $ chezmoi init --apply$USERNAME/dotfiles.git
  • Pull and apply the latest changes, on any machine, from your repository:

    $ chezmoi update -v
  • Pull the latest changes from your repository and see what would change, without actually applying the changes:

    $ chezmoi git pull -- --autostash --rebase && chezmoi diff

Working with templates

  • Print the available template data (including the full list of variables specified for templates):

    $ chezmoi data 
  • Add a file as a template:

    $ chezmoi add --template $FILE 
  • Makes an existing file a template:

    $ chezmoi chattr +template $FILE 
  • Print the target contents of a file, without changing the file:

    $ chezmoi cat $FILE 
  • Test and debugg templates:

    $ chezmoi execute-template '{{ .chezmoi.sourceDir }}'
    $ chezmoi execute-template '{{ .chezmoi.os }}' / '{{ .chezmoi.arch }}'
    $ echo '{{ .chezmoi | toJson }}' | chezmoi execute-template
    $ chezmoi execute-template --init --promptString < ~/.local/share/chezmoi/.chezmoi.toml.tmpl

If this cheat sheet has been useful to you, then please consider leaving a star here.