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 conflicting files with file-conflict-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 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 all-users instead.

Development

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

Example configuration

type: chezmoi
# Git repository to initialize
repository: "https://example.org/user/dotfiles" # Required - Default: n/a  - Expects type: string
# Whether to enable the modules services globally for all users, if false users need to enable services manually
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 have 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
# What to do when file different that exists on your repo is has been changed or exists locally. Accepts "skip" or "replace"
file-conflict-policy: "skip" # Optional - Default: "skip" - Expects type: string

Configuration options

repository: (required string)

Git repository to initialize.

all-users: (optional boolean)

Whether to enable the modules services globally for all users, if false users need to enable services manually.

Default: true

run-every: (optional string)

Dotfiles will be updated with this interval.

Default: 1d

wait-after-boot: (optional string)

Dotfile updates will wait this long after a boot before running.

Default: 5m

disable-init: (optional boolean)

Disable the service that initializes repository on users that are logged in or have linger enabled UI.

Default: false

disable-update: (optional boolean)

Disable the timer that updates chezmoi with the set interval.

Default: false

file-conflict-policy: (optional enum)

What to do when file different that exists on your repo is has been changed or exists locally. Accepts “skip” or “replace”.

Possible values: skip, replace
Default: skip