Add initial script documentation

docs/HOWTO.md

@@ -13,6 +13,7 @@
   * [Use Vault to keep your secrets](#use-vault-to-keep-your-secrets)
   * [Use a generic tool to keep your secrets](#use-a-generic-tool-to-keep-your-secrets)
   * [Use templates variables to keep your secrets](#use-templates-variables-to-keep-your-secrets)
+* [Run extra commands during chezmoi apply](#run-extra-commands-during-chezmoi-apply)
 * [Import archives](#import-archives)
 * [Export archives](#export-archives)
 * [Use non-git version control systems](#use-non-git-version-control-systems)
@@ -373,6 +374,35 @@ Your `~/.local/share/chezmoi/private_dot_gitconfig.tmpl` can then contain:
 Any config files containing tokens in plain text should be private (permissions
 `0600`).
 
+## Run extra commands during chezmoi apply
+
+chezmoi includes support for scripts which are run each time `chezmoi apply` is
+run. These can be useful for installing packages or performing other
+machine-specific configuration. Scripts are run in the destination directory and
+should be idempotent.
+
+Scripts must be created manually in the source directory and have the
+prefix `run_`. For example:
+
+    $ chezmoi cd
+    $ cat > run_echo_hello
+    #!/bin/sh
+    echo hello
+    <Ctrl-D>
+    $ chezmoi apply
+    hello
+
+If a script has the suffix `.tmpl` then it is expanded as a template before
+being executed.
+
+In verbose mode, the script's contents will be printed before executing it. In
+dry-run mode, the script is not executed.
+
+If you want a script to only run once, then give it the prefix `run_once_`.
+chezmoi will remember when it has executed a script and will only run it again
+if its name (excluding any `run_once_` prefix and `.tmpl` suffix) changes, or if
+its contents change.
+
 ## Import archives
 
 It is occasionally useful to import entire archives of configuration into your

docs/REFERENCE.md

@@ -175,23 +175,26 @@ special, and are collectively referred to as "attributes":
 | Prefix/suffix        | Effect                                                                            |
 | -------------------- | ----------------------------------------------------------------------------------|
 | `encrypted_` prefix  | Encrypt the file in the source state.                                             |
+| `once_` prefix       | Only run script once.                                                             |
 | `private_` prefix    | Remove all group and world permissions from the target file or directory.         |
 | `empty_` prefix      | Ensure the file exists, even if is empty. By default, empty files are removed.    |
 | `exact_` prefix      | Remove anything not managed by chezmoi.                                           |
 | `executable_` prefix | Add executable permissions to the target file.                                    |
+| `run_` prefix        | Treat the contents as a script to run.                                            |
 | `symlink_` prefix    | Create a symlink instead of a regular file.                                       |
 | `dot_` prefix        | Rename to use a leading dot, e.g. `dot_foo` becomes `.foo`.                       |
 | `.tmpl` suffix       | Treat the contents of the source file as a template.                              |
 
-Order is important, the order is `exact_`, `private_`, `empty_`, `executable_`,
-`symlink_`, `dot_`, `.tmpl`.
+Order is important, the order is `run_`, `exact_`, `private_`, `empty_`,
+`executable_`, `symlink_`, `once_`, `dot_`, `.tmpl`.
 
 Different target types allow different prefixes and suffixes:
 
 | Target type   | Allowed prefixes and suffixes                                      |
 | ------------- | ------------------------------------------------------------------ |
 | Directory     | `exact_`, `private_`, `dot_`                                       |
 | Regular file  | `encrypted_`, `private_`, `empty_`, `executable_`, `dot_`, `.tmpl` |
+| Script        | `run_`, `once_`, `.tmpl`                                           |
 | Symbolic link | `symlink_`, `dot_`, `.tmpl`                                        |
 
 ## Special files