chezmoi

Setup up chezmoi, creating a Git repository in ~/.local/share/chezmoi

$ chezmoi init

$ chezmoi init [repository_url]

$ chezmoi add [path/to/dotfile1 path/to/dotfile2 ...]

$ chezmoi re-add [path/to/dotfile1 path/to/dotfile2 ...]

$ chezmoi edit [path/to/dotfile_or_symlink]

$ chezmoi diff

$ chezmoi -v apply

$ chezmoi update

chezmoi [global-flags] <command> [command-flags] [arguments...]

init [repo]
    
Initializes chezmoi in your home directory and clones your dotfiles repository. If repo is omitted, it defaults to a common location.

add [path...]
    
Adds files or directories from your home directory to chezmoi's source directory, preparing them for management.

apply
    
Applies changes from your source directory to your home directory, synchronizing dotfiles and creating necessary links/files.

diff
    
Shows the differences between your source directory and your home directory, indicating what apply would do without making actual changes.

edit [path...]
    
Opens the source file corresponding to a given destination path in your configured editor, allowing you to modify your dotfiles source.

status
    
Shows the status of your dotfiles, indicating which are out of sync with your source directory and why.

update
    
Pulls changes from your remote dotfiles repository and then applies them, effectively updating your local dotfiles.

doctor
    
Checks for common problems and misconfigurations within your chezmoi setup and suggests solutions.

--dry-run
    
Simulates the execution of a command without making any actual changes to the filesystem. Useful for previewing.

--verbose
    
Enables verbose output, showing more details about what chezmoi is doing during execution.

--force
    
Forces the operation, overriding existing files or ignoring warnings that would otherwise prevent the command from executing.

chezmoi is a powerful and flexible dotfile manager that helps you manage your configuration files across multiple machines. It works by maintaining a source directory (usually version-controlled with Git) containing your desired dotfile state. When you run chezmoi apply, it synchronizes your home directory with this source, creating symlinks, copying files, and even running scripts.

A key feature is its ability to use Go templates, allowing for machine-specific configurations (e.g., different hostnames, OS types, or user settings). It also supports secrets management by integrating with external password managers. chezmoi prioritizes idempotence, ensuring that apply can be run repeatedly without unintended side effects. It provides excellent diff and status capabilities to preview changes before applying them.

Steep learning curve for advanced features like templating, secrets management, and cross-platform configurations.
Initial setup requires careful planning to avoid accidental overwrites of existing files.
Can be opinionated about file structures (e.g., dotfiles typically reside in ~/.local/share/chezmoi by default).
Requires a basic understanding of Git for managing the dotfiles source repository.

chezmoi supports Go's text/template syntax, allowing for dynamic configuration based on host-specific variables (e.g., hostname, OS, user, machine architecture), environment variables, or even the output of external commands. This enables a single source of truth for dotfiles that can adapt to diverse system environments.

It can integrate with various external password managers (e.g., LastPass CLI, 1Password CLI, Bitwarden CLI, gopass, pass) to securely manage sensitive data within your dotfiles. This prevents secrets from being committed directly to your version control system, enhancing security.

chezmoi is designed to be idempotent; running chezmoi apply multiple times will consistently result in the same desired state without unintended side effects. It provides robust diff and status commands to preview changes meticulously before applying them, significantly enhancing safety and control over your configuration.

chezmoi was created by Tom Payne and first released in 2019. It was designed to address perceived shortcomings in existing dotfile managers, particularly regarding idempotence, cross-platform compatibility, and robust templating. It quickly gained popularity due to its powerful features, active development, and clear focus on safety and reliability, establishing itself as a modern standard for dotfile management.

git(1), stow(1), yadm(1), rsync(1), dotbare(1)