Skip to content

Hooks

Jump to bottom
Pol Rivero edited this page May 30, 2025 · 6 revisions

You can extend the functionality of doot by defining custom hooks to be run at different stages of execution.

Hooks are shell scripts (or any executable file) located inside <dotfiles_dir>/doot/hooks/<hook_name>/. When a given condition is met, all files inside the corresponding hook directory are executed sequentially, in alphabetical order. If you need your hooks to run in a specific order, I recommend adding a number prefix (01.prepare-files.sh, 02.other-actions.sh, ...).

A hook can abort the execution by returning a non-zero exit code. The other files in the hook directory will not be executed, and doot will exit immediately.

Tip

The working directory ($PWD) of the executed scripts will always be the dotfiles repository, regardless of where the doot command was executed from.

Warning

If your hooks are shell scripts, make sure to add the appropriate shebang (for example, #!/bin/bash). Otherwise the file will be intepreted as a binary and the hook will fail with the message "exec format error".
Additionally, make sure the hook file has executable permissions set. You can do this by running chmod +x <file>.

Available hooks

  • doot/hooks/before-update/*: Before the dotfiles directory is scanned for changes. Affects install, clean and bootstrap commands (see lifecycles below).

  • doot/hooks/after-update/*: After the symlinks have been created or removed. Affects install, clean and bootstrap commands (see lifecycles below).

  • doot/hooks/before-bootstrap/*: After the dotfiles repository has been cloned, before it is installed.

  • doot/hooks/after-bootstrap/*: After the bootstrap process. This is a good place to install packages and enable services.

Lifecycles

Install:

  1. Run before-update hooks.
  2. Scan the dotfiles directory for changes.
  3. Create and delete symlinks.
  4. Run after-update hooks.

Clean:

  1. Run before-update hooks.
  2. Delete symlinks.
  3. Run after-update hooks.

Bootstrap:

  1. Clone dotfiles repository.
  2. Unlock private files with decryption key (if applicable).
  3. Run before-bootstrap hooks.
  4. Run before-update hooks.
  5. Scan the dotfiles directory for links to be created.
  6. Create symlinks.
  7. Run after-update hooks.
  8. Run after-bootstrap hooks.

Home

Basic usage

Getting Started

Commonly used commands

Advanced usage

Private (encrypted) files

Bootstrap repository

Pull changes

Define hooks

Define custom commands

Installing files as hardlinks

Tips

Set explore_excluded_dirs = false

Other

Should I use doot?

Clone this wiki locally