Use Scripts to Perform Actions

Automate tasks with chezmoi’s script system

Understand how scripts work

chezmoi supports scripts that execute when you run chezmoi apply. Scripts are files in the source directory with the run_ prefix, executed in alphabetical order.

Script types

run_

Execute every time you run chezmoi apply

run_onchange_

Execute only when script contents have changed

run_once_

Execute once per unique content version

All scripts should be idempotent (safe to run multiple times). Scripts break chezmoi’s declarative approach and should be used sparingly.

Script timing

Scripts normally run while chezmoi updates your dotfiles:

a.txt → run_b.sh → c.txt

Use before_ or after_ attributes to control timing:

Before updates

run_once_before_install-password-manager.sh

Script requirements

1. Create manually

   chezmoi cd
   touch run_install-packages.sh
   chmod +x run_install-packages.sh
   

   No need to set executable bit - chezmoi handles it.

2. Include shebang or use binary

   #!/bin/bash
   echo "Installing packages..."
   

   Scripts must include a #! line or be an executable binary.

3. Template support

   run_install.sh.tmpl

   {{ if eq .chezmoi.os "linux" -}}
   #!/bin/sh
   sudo apt install ripgrep
   {{ else if eq .chezmoi.os "darwin" -}}
   #!/bin/sh
   brew install ripgrep
   {{ end -}}
   

   Scripts with .tmpl suffix are templated. If template resolves to whitespace, script won’t execute.

Scripts in .chezmoiscripts/ directory are executed without creating a corresponding directory in the target state.

Set environment variables

Configure extra environment variables for scripts in your config:

~/.config/chezmoi/chezmoi.toml

[scriptEnv]
    MY_VAR = "my_value"
    API_KEY = "{{ onepassword "api-key" }}"

chezmoi automatically sets:

• CHEZMOI=1
• CHEZMOI_OS (e.g., linux, darwin)
• CHEZMOI_ARCH (e.g., amd64, arm64)
• Other template data as CHEZMOI_* variables

Don’t show scripts in chezmoi diff/chezmoi status

Exclude from diff

~/.config/chezmoi/chezmoi.toml

[diff]
    exclude = ["scripts"]

Scripts won’t appear in chezmoi diff output.

Exclude from status

~/.config/chezmoi/chezmoi.toml

[status]
    exclude = ["scripts"]

Scripts won’t show R status in chezmoi status.

Install packages with scripts

1. Create installation script

   chezmoi cd
   touch run_onchange_install-packages.sh
   
2. Add package installation commands

   Simple version

   #!/bin/sh
   sudo apt install ripgrep
   
3. Apply changes

   chezmoi apply
   

   Script runs on first apply. With run_onchange_, it won’t run again unless contents change.

Name your template run_onchange_install-packages.sh.tmpl to install platform-specific packages automatically.

Run a script when another file changes

Use content checksums to trigger scripts when other files change:

run_onchange_dconf-load.sh.tmpl

#!/bin/bash

# dconf.ini hash: {{ include "dconf.ini" | sha256sum }}
dconf load / < {{ joinPath .chezmoi.sourceDir "dconf.ini" | quote }}

How it works:

1. Template includes SHA256 hash of dconf.ini in a comment
2. When dconf.ini changes, the hash changes
3. Changed hash means changed script content
4. chezmoi reruns the run_onchange_ script

Add dconf.ini to .chezmoiignore so chezmoi doesn’t create it in your home directory.

Clear the state of all run_onchange_ and run_once_ scripts

chezmoi tracks script execution in persistent state.

Clear run_onchange_ state

chezmoi state delete-bucket --bucket=entryState

All run_onchange_ scripts will run again on next chezmoi apply.

Clear run_once_ state

chezmoi state delete-bucket --bucket=scriptState

All run_once_ scripts will run again on next chezmoi apply.

Clearing state causes scripts to run again. Ensure your scripts are idempotent before doing this.

Real-world examples

run_onchange_before_install-homebrew.sh.tmpl

{{ if eq .chezmoi.os "darwin" -}}
#!/bin/bash

if ! command -v brew &> /dev/null; then
    echo "Installing Homebrew..."
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
fi
{{- end }}