chezmoi

The chezmoi module takes care of installing, initializing and updating your dotfiles. Each feature can be enabled or disabled individually.

Installation of the chezmoi binary happens at build time and is done by downloading the amd64 binary from the latest release to /usr/bin/chezmoi. This can be disabled by setting install to false. (defaults: true)

Choose how chezmoi handles changed files with changed-file-policy. The following values are valid: "skip" Will not take any action if the file has changed from what is in your dotfiles repository. This executes chezmoi update --no-tty --keep-going under the hood. "replace" Will overwrite the file if it has changed from what is in your dotfiles repository. This executes chezmoi update --no-tty --force under the hood.

See chezmois documentation for --no-tty, --keep-going and --force for details.

A systemd user service is installed that will initialize a chezmoi repository on chezmoi’s default path (~/.local/share/chezmoi) for any user when it logs in, or at boot if it has lingering enabled. The service will only run if ~/.local/share/chezmoi does not exist. Set repository to the URL of your dotfiles repository. (eg. repository: https://example.org/user/dotfiles)

Note

The value of repository will be passed directly to chezmoi init --apply ${repository}. See the chezmoi init documentation for detailed syntax.

Set disable_init to true if you do not want to install the init service.

Caution

If repository is not set, and disable_init is false the module will fail, due to not being able to initialize the repository.

Set enable_all_users to false if you want to install the update and initialization services, but do not want them enabled for all users. You can enable them manually instead when the system has been installed:

To enable the services for a single user, run the following command as that user:

systemctl enable --user chezmoi-init.service chezmoi-update.timer`

To manually enable the services for all users, run the following command with sudo:

sudo systemctl enable --user chesmoi-init.service chezmoi-update.timer

To turn on lingering for a given user, run the following commmand with sudo:

Note

By default, any systemd units in a user’s namespace will run after the user logs in, and will close after the user closes their last session. When you enable lingering for a user, that user’s units will run at boot and will continue running even if the user has no active sessions.

If your dotfiles only contain things used by humans, such as cosmetic settings and aliases, you shouldn’t need this. If you understand the above implications, and decide you need this feature, you can enable it with the following command, after installation:

sudo loginctl enable-linger <username>`

You can configure the interval between updates of your dotfiles by setting the value of run_every. The string is passed directly to OnUnitInactiveSec. (default: ‘1d’) See systemd.time documenation for detailed syntax. Examples: ‘1d’ (1 day - default), ‘6h’ (6 hours), ‘10m’ (10 minutes)

Likewise, wait_after_boot configures the delay between the system booting and the update service starting. This follows the same syntax as run_every. (default: ‘5m’)

The installation of the initialization service and the update service can be disabled separately by setting disable_init and/or disable_update to true. (Both default: false)

Caution

Note that this will skip the installation of the services completely. If you want them installed but disabled, see enable_all_users instead.

Development

Setting DEBUG=true inside chezmoi.sh will enable additional output in bash useful for debugging.

Example configuration

type: chezmoi
# Installs chezmoi to /usr/bin/chezmoi from latest Github release
install_chezmoi: true # Optional - Default: true  - Expects type: boolean
# () Git repository to initialize
repository: "https://example.org/user/dotfiles" # Required - Default: n/a  - Expects type: string
# Enable the modules services globally for all users
enable_all_users: true # Optional - Default: true - Expects type: boolean
# Dotfiles will be updated with this interval
run_every: '1d' # Optional - Default: '1d' - Expects type: string
# Dotfile updates will wait this long after a boot before running
wait_after_boot: '5m' # Optional - Default: '5m' - Expects type: string
# Disable the service that initializes `repository` on users that are logged in or has linger enabled
disable_init: false # Optional - Default: false - Expects type: boolean
# Disable the timer that updates chezmoi with the interval set above
disable_update: false # Optional - Default: false - Expects type: boolean
# Policy for handling file that has changed on disk compared to your repo. Accepts "skip" or "replace"
changed-file-policy: "skip" # Optional - Default: "skip" - Expects type: string