What is the difference between run_onchange_ and run_once_?

[tmeijn]

Hi everyone, I have difficulty to really grasp the difference between run_onchange_ and run_once_.

From the docs:

• run_onchange_ scripts: These scripts are only executed if their content has changed since the last time they were run.
• run_once_ scripts: These scripts are executed once for each unique version of the content. If the script is a template, the content is hashed after template execution. chezmoi tracks the content's SHA256 hash and stores it in a database. If the content has been run before (even under a different filename), the script will not run again unless the content itself changes.

Both state that they will run when their content has changed so I do not see the difference there. run_once_ you can optionally control the running order with the before and after modifier which you cannot seem to do with run_onchange.

Can anybody explain the practical difference and when you used one over the other?

Thanks!

[jarodtaylor]

This really confused me as well, but I think if I understand it correctly:

run_onchange (you can use _before or _after with these btw way, not just the run_once) will run any time you change the script (be it the name from run_onchange_before-do-something.sh.tmpl to run_onchange_before-do-something-else.sh.tmpl) or if the contents of that file changes. So, if since the last time you ran chezmoi apply anything about that file changed, it will run.

run_once only runs for each unique version (which is what confused me, because I would think any change changes the uniqueness). With run_once (if I understand correctly) Chezmoi tracks the SHA256 of the content of that file. So, if you changed the filename from run_onchange_before-do-something.sh.tmpl to run_onchange_before-do-something-else.sh.tmpl the content SHA doesn't change, so run_once wouldn't run when you ran chezmoi apply.

To be honest, I'm not entirely sure when you would use run_once. I'm sure there are reasons for it since @twpayne created this functionality, but I am unsure when I would use it. I have only usedrun_onchange but I've also only been using Chezmoi for a month. haha

I think run_once would not run if you changed the files permissions/metadata, either, because I believe run_once is solely based on that SHA of the content. If the file's content doesn't change, it won't run. I think this only runs if anything changes the content of the script causing the SHA to change, but not changes to the actual file itself (name, permissions, metadata, etc).

[jarodtaylor]

Here's another section of the documentation that mentions it: https://www.chezmoi.io/developer-guide/architecture/#persistent-state

I love Chezmoi, but I will say that some of the documentation for different commands, features, etc are spread out so you end up having to search the documentation site for the variations of the documentation. This is one example, since run_once and run_onchange are mentioned in multiple places, as opposed to it being centralized for "all things" run_once or whatever. If I get time, I should help Tom out and raise some PRs to help with some of the documentation. The tool is amazing, though!

[twpayne]

@jarodtaylor's explanation is correct.

The reason for having the two types of script is historical.

Initially there were only run_ scripts and run_once_ scripts, with the idea that run_once_ scripts would be used for expensive operations that only needed to be run once, e.g. installing packages.

Later, I realized that this was not sufficient. The specific case was a script that configured something else by running a program (e.g. running gsettings for GNOME or defaults for macOS). If you used a run_once_ script for this, when you changed the script back to a previous setting, chezmoi wouldn't run it because chezmoi had already run a script with the exact contents before. Hence, run_onchange_ scripts were born, which chezmoi runs whenever their contents change.

Generally speaking, you should use run_onchange_ script unless you know that you have a good reason to use a run_once_ script.