# atmos git hooks run

Execute the command or ordered steps configured for a Git hook under [`git.hooks`](/cli/configuration/git#local-git-hooks). This is what the `.git/hooks/*` shims installed by [`atmos git hooks install`](/cli/commands/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.

## Usage

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

Given this configuration:

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

Git invokes the installed shim, which runs:

```shell
atmos git hooks run commit-msg .git/COMMIT_EDITMSG
```

## Examples

```shell
# 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

- [`atmos git hooks install`](/cli/commands/git/hooks/install) — install the shims that call this command
- [Workflows](/cli/configuration/workflows) — what hook commands typically invoke
- [Git Configuration](/cli/configuration/git#local-git-hooks) — the `git.hooks` section

For inline scripts and execution details, see [Git hook steps](/cli/configuration/git#inline-script-steps).