How to Install and Use Chezmoi on Linux to Manage Dotfiles Across Multiple Machines

Managing configuration files (dotfiles) across personal workstations, headless home servers, and cloud virtual machines frequently becomes cumbersome without a dedicated synchronisation strategy. While basic Git repositories can track files in a home directory, handling machine-specific parameters, secret tokens, and disparate directory hierarchies requires significant scripting overhead. chezmoi is a purpose-built dotfile manager written in Go that manages personal configuration files across multiple machines using declarative templates, Git version control, and encrypted password-manager integration.

Installing chezmoi Across Linux Distributions

Because chezmoi is compiled into a single static binary with zero external runtime dependencies, installation is straightforward across modern Linux environments.

On Debian, Ubuntu, and derivative distributions running modern package repositories:

sudo apt update
sudo apt install chezmoi

On Fedora, CentOS Stream, or RHEL-based systems:

sudo dnf install chezmoi

On Arch Linux and Manjaro, obtain the package directly from official extra repositories:

sudo pacman -S chezmoi

For minimal systems or distributions without native package repository entries, run the official POSIX installation script to place the binary inside your user directory (~/.local/bin):

sh -c "$(curl -fsLS get.chezmoi.io)" -- -b ~/.local/bin

Verify that the binary operates correctly by checking its installed version:

chezmoi --version

Initialising Your Source Directory and Git Repository

Unlike conventional dotfile workflows that directly transform your home directory into a Git repository, chezmoi maintains an independent working directory located at ~/.local/share/chezmoi. Your active files in $HOME remain untouched until explicit apply commands are issued.

Initialise the local source state:

chezmoi init

If you already maintain an existing Git repository hosted on GitHub, GitLab, or Codeberg, initialise directly against that remote URL:

chezmoi init https://github.com/username/dotfiles.git

Adding Configuration Files to chezmoi Management

To begin tracking existing user configurations, supply the target file path directly to the add command. For instance, to manage your Bash configuration and Neovim settings:

chezmoi add ~/.bashrc
chezmoi add ~/.config/nvim/init.lua

To inspect what chezmoi recorded in its source repository, launch an interactive shell within the source repository directory:

chezmoi cd

Inside this repository, you will observe that standard dotfiles are prefixed with dot_ (such as dot_bashrc) and directories are prefixed with regular names or dot_config. Type exit to return to your standard terminal environment.

Editing and Applying Dotfile Modifications

Whenever you need to adjust a tracked configuration, execute the edit subcommand rather than modifying files directly in your home directory:

chezmoi edit ~/.bashrc

This command opens the source copy in your preferred editor (defined by your $EDITOR or $VISUAL environment variable). Once saved, review the exact differences between your source state and active destination files:

chezmoi diff

If the previewed changes reflect your intended adjustments, commit them to your target system:

chezmoi apply -v

The -v (verbose) flag prints each modification directly to the terminal standard output, ensuring total transparency during file writes.

Managing Machine Differences with Go Templates

A primary strength of chezmoi is its ability to adapt file contents dynamically based on machine characteristics such as hostname, operating system, or custom variables. Convert any standard file into an active Go template by appending the .tmpl extension:

chezmoi add --template ~/.gitconfig

Open the template for modification:

chezmoi edit ~/.gitconfig

Inside the template file, insert conditional blocks to tailor email addresses or system architectures:

[user]
    name = Alex Smith
{{- if eq .chezmoi.hostname "workstation-office" }}
    email = [email protected]
{{- else }}
    email = [email protected]
{{- end }}

[core]
    editor = nvim
{{- if eq .chezmoi.os "linux" }}
    autocrlf = input
{{- end }}

To preview how this template resolves on the current machine without altering disk state, execute:

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

Synchronising Configurations Across Secondary Workstations

To deploy your configurations onto a fresh laptop or cloud compute instance, ensure chezmoi and git are installed, then run:

chezmoi init --apply https://github.com/username/dotfiles.git

On existing systems, pulling upstream modifications and applying them to your local environment requires only one command:

chezmoi update -v

This pulls remote Git commits, renders any machine-specific templates against local attributes, and updates your home directory configurations cleanly.