chezmoi

NAME

chezmoi - edit and apply the dotfiles

SYNOPSIS

chezmoi init --apply ssh://git@git.jdoe-site.com:2222/home/git/dotfiles.git
chezmoi apply
chezmoi edit ~/.config/hypr/hyprland.lua
chezmoi update

DESCRIPTION

chezmoi writes the files in your home directory from the dotfiles repo. It writes no file outside your home directory. Partitions, the bootloader, /etc, and the system packages are manual work.

What chezmoi manages

chezmoi manages the configuration files and the packages that the configurations need. .chezmoidata/packages.yaml contains the package list. 10-packages.sh installs each package that is not present when chezmoi applies the dotfiles.

The script does not print a message when all packages are present. It runs sudo only when it installs a package.

The package groups are different for each machine. The machine identity is native or wsl, from the profile template in .chezmoitemplates/. .chezmoi.os shows linux on both machines. The native: group contains the desktop stack. The wsl: group contains the Azure CLI. The aur: group uses yay on bare metal only.

The source state

.chezmoiroot names home/. chezmoi reads no file outside home/. docs/ and README.md are beside home/ and are not targets. A file in home/ becomes a file in your home directory, unless .chezmoiignore names it. chezmoi managed shows each file that chezmoi writes.

Edit a target

1. Run chezmoi edit <path> to change a target.

2. Run chezmoi apply.

For a new target, write the file in your home directory first. Then run chezmoi add.

An application can write a file that chezmoi manages. qutebrowser bookmarks are an example. After the change, run chezmoi re-add for the file. Then commit the repository. Without the commit, chezmoi prompts to overwrite the file the next time you apply.

Source-only files have no target. Edit source-only files in the repository: .chezmoidata/, .chezmoi.toml.tmpl, .chezmoiexternal.toml.tmpl, docs/, and the scripts.

Apply, update, diff

chezmoi apply writes each target. chezmoi update gets the repository and then applies it.

If no file is different, chezmoi diff shows no output. This is the check for changes that are not applied. Add --no-pager when no terminal shows the output. Without a terminal, the pager stops, and chezmoi does not continue.

diff.exclude omits the scripts from the diff. Without the exclusion, the rendered packages script adds 295 lines to the output. A change to a different file is then not visible. chezmoi status marks with R each script that chezmoi apply will run. The command chezmoi diff --exclude=none shows the contents of these scripts.

Scripts

A run_onchange_ script runs when its rendered text changes. A run_after_ script shows as pending in each diff, even when its text did not change.

• 10-packages.sh installs the package groups. If no AUR helper exists, it shows the yay procedure.
• 20-ssh-agent.sh enables ssh-agent.socket. On WSL, systemd in /etc/wsl.conf and linger are necessary.
• 21-op-keys.sh enables op-keys.service on bare metal. The script does not enable the unit until the token file exists.
• 90-alacritty-wsl-host.sh writes the Windows Alacritty configuration through /mnt/c. chezmoi maps one source tree to one destination. This file is not in the chezmoi diff output, and chezmoi managed does not show it.

The token in ~/.config/op/token.env is a credential. chezmoi does not manage it. The session start page shows how op-keys loads the key into the agent.

The signing key

private_dot_ssh/allowed_signers.tmpl contains jdoe_id for commit signing. For a new key, replace the ssh-ed25519 line with the public half of the key. Keep {{ .email }} at the start of the line.

{{ .email }} ssh-ed25519 AAAA... me@jdoe-site.com

The line changes only when the key changes. A new installation copies the same key. GitHub needs jdoe_id.pub as a Signing Key, in addition to an Authentication Key.

One clone per machine

The clone at ~/.local/share/chezmoi is the chezmoi source directory. It is the only clone on the machine. Two clones of one repository diverge. The terminal and workflow page shows the shell for the commits.

SEE ALSO

session-start(1), terminal(1)