Skip to main content

atmos git hooks run

Execute the command or ordered steps configured for a Git hook under git.hooks. This is what the .git/hooks/* shims installed by atmos git hooks install invoke, but it can also be run directly — useful for testing a hook without triggering it through Git. Steps run from the repository root, even when you invoke the hook from a subdirectory.

atmos git hooks run --help

Usage​

atmos git hooks run <hook-name> [args...]

Given this configuration:

git:
  hooks:
    pre-commit:
      command: atmos workflow pre-commit
    commit-msg:
      command: atmos workflow commit-msg -- "$1"

Git invokes the installed shim, which runs:

atmos git hooks run commit-msg .git/COMMIT_EDITMSG

Examples​

# Test a hook without committing
atmos git hooks run pre-commit

# Run a hook that takes arguments (commit-msg receives the message file path)
atmos git hooks run commit-msg .git/COMMIT_EDITMSG

Behavior​

  • Loads the Atmos configuration for the current repository and selects the hook's command or steps.
  • Runs steps in order through the registered step library, from the repository root even when invoked from a subdirectory. The step metrics summary is off by default for hooks. Embedded Starlark runs inside Atmos; a failed step stops the hook. Hook arguments are available as ctx.args in Starlark steps and as $1, "$@", and ATMOS_GIT_HOOK_ARGS in shell steps.
  • Runs command hooks through the shared shell runner with the inherited process environment, including PATH. Prepare any tools or identity credentials before invoking the hook.
  • Forwards hook arguments and stdin to command hooks — hooks such as pre-push and pre-receive receive their input on stdin, not argv. For steps hooks, Atmos saves the data Git pipes to pre-push, pre-receive, post-receive, post-rewrite, reference-transaction, and proc-receive to a temporary file whose path is in ATMOS_GIT_HOOK_STDIN, and the first shell step also receives the data on its standard input. Atmos removes the file when the hook ends.
  • Propagates the command's exit code, so a failing hook command blocks the Git operation exactly as a hand-written hook would. For steps hooks the exit code is the failing step's: a Starlark fail() exits with 1, and errors.build("message").with_exit_code(5).fail() exits with 5.
  • Fails a prompt step that has no default: when the hook runs without a terminal, with a hint that setting default: lets the step run there.
  • Lets a later configuration source replace an earlier hook definition: switching a hook between steps: and command: replaces the earlier form.
  • Fails with a clear error listing the configured hooks when <hook-name> is not configured under git.hooks.

Arguments​

hook-name (required)

The Git hook to run, matching a key under git.hooks (pre-commit, commit-msg, pre-push, ...).

args... (optional)

Arguments forwarded verbatim to the configured command — exactly what Git passes to the hook (for example, the commit message file path for commit-msg). Arguments are passed through even when they look like flags.

Related​

For inline scripts and execution details, see Git hook steps.