Managing Dotfiles Across Multiple Machines with chezmoi

Keeping configuration files synchronized across different environments is a common challenge for developers. chezmoi addresses this by helping you manage your dotfiles across multiple diverse machines, securely [1]. Instead of relying on symlink farms or unstructured scripts, chezmoi evaluates the configured state of your dotfiles. When you run chezmoi apply, chezmoi calculates the desired contents for each of your dotfiles and then makes the minimum changes required to make your dotfiles match your desired state [2]. Whether you are working on a Raspberry Pi or managing a complex multi-machine development environment spanning Linux, macOS, and Windows, chezmoi keeps your environment consistent.

Initializing Your Source State

To begin managing your dotfiles, you first need to establish a source repository. The chezmoi init command will create a new git local repository in ~/.local/share/chezmoi where chezmoi will store its source state [2]. This hidden directory acts as the single source of truth for your configuration files.

By default, chezmoi only modifies files within this isolated working copy rather than immediately altering your live home directory. Once initialized, you can start tracking individual configuration files, such as your .bashrc or .zshrc. This isolation prevents accidental misconfigurations from taking effect until you explicitly apply the changes.

Modifying and Previewing Configuration Changes

When you need to update a configuration file, you should make changes within the chezmoi source state rather than editing the live file directly. As an example, the chezmoi edit command will open ~/.local/share/chezmoi/dot_bashrc in your $EDITOR [2].

Before committing these updates, you can inspect the exact modifications, as all chezmoi commands accept the -v (verbose) flag to print out exactly what changes they will make to the file system [2]. Furthermore, using the -n (dry run) flag to not make any actual changes allows you to preview synchronization operations without risk [2]. Combining -n and -v provides a detailed, risk-free view of the pending synchronization, ensuring you never overwrite critical data accidentally.

Utilizing Templates and Managing Secrets

One of the most powerful capabilities of chezmoi is its ability to handle environmental differences programmatically. Your dotfiles can be templates (using Go text/template syntax), and predefined variables allow you to change behavior depending on operating system, architecture, and hostname [3]. This allows a single source file to intelligently adapt when applied to a macOS workstation versus a Linux server.

Additionally, chezmoi supports securely handling credentials, allowing you to manage secrets (e.g. passwords, access tokens, and private keys) securely and seamlessly using a password manager and/or encrypt whole files with your favorite encryption tool [3]. This means you can keep your dotfiles repository public on platforms like GitHub without exposing sensitive keys or API tokens, relying instead on external vaults for decryption on the target machine.

By storing the source state in a standard Git repository, you can securely version-control your configurations, push them to a remote server, and quickly replicate your meticulously customized environment on any new machine.

Sources

[1] https://github.com/twpayne/chezmoi [2] https://github.com/twpayne/chezmoi/blob/master/assets/chezmoi.io/docs/quick-start.md [3] https://github.com/twpayne/chezmoi/blob/master/assets/chezmoi.io/docs/what-does-chezmoi-do.md