Documentation
Lifecycle Hooks
Run custom commands before and after push/pull operations
Overview
Lifecycle hooks let you run shell commands at key points during push and pull. Use them to export extension lists, rebuild caches, reload configs, or anything else your workflow needs.
Configuration
Define hooks in ~/.configsync/config.yaml under the hooks key. Each hook is an array of shell commands.
hooks:
pre_push:
- code --list-extensions > ~/.config/vscode-extensions.txt
- brew bundle dump --file=~/.config/Brewfile --force
post_push: []
pre_pull: []
post_pull:
- brew bundle install --file=~/.config/Brewfile --no-lock
- source ~/.zshrc
Available Hooks
| pre_push | Runs before push begins. Abort push on failure. |
| post_push | Runs after a successful push. Warns on failure but does not undo the push. |
| pre_pull | Runs before pull begins. Abort pull on failure. |
| post_pull | Runs after a successful pull. Warns on failure but does not undo the pull. |
Environment Variables
ConfigSync sets the following environment variables before running each hook:
| CONFIGSYNC_HOOK | Name of the current hook (e.g. pre_push, post_pull) |
| CONFIGSYNC_ENV | Active environment name (e.g. dev, production), if set |
| CONFIGSYNC_PROFILE | Active profile name (e.g. work, personal), if set |
Examples
Export VS Code extensions before every push:
hooks:
pre_push:
- code --list-extensions > ~/.config/vscode-extensions.txt
Restore Homebrew packages after pulling:
hooks:
post_pull:
- brew bundle install --file=~/.config/Brewfile --no-lock
Reload shell config after pulling:
hooks:
post_pull:
- source ~/.zshrc
Behavior Details
- Each command has a 5-minute timeout. If a command exceeds this, it is killed and treated as a failure.
- Commands run in the user's default shell (e.g.
$SHELL -c "command"). - Commands run sequentially in the order listed.
- Pre-hooks abort on the first failure; remaining commands are skipped.
- Post-hooks run all commands even if earlier ones fail.