# atmos git hooks install

Write local `.git/hooks/<hook>` shim scripts for the hooks configured under [`git.hooks`](/cli/configuration/git#local-git-hooks). Each shim delegates to `atmos git hooks run`, keeping all hook logic in `atmos.yaml` where it is versioned, shared, and executed through Atmos workflows and custom commands.

## Usage

```shell
atmos git hooks install [hook-name...] [flags]
```

Given this configuration:

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

`install` writes a shim for each configured hook. It works in both regular clones
and linked worktrees. At runtime it uses `git rev-parse --show-toplevel` to find
the current checkout, then runs its executable `build/atmos` (or `build/atmos.exe`)
when present.

When installed by a development build, the shim falls back to `atmos` on `PATH` if
the current worktree has no executable build. It never records the installing
worktree's build path, so linked worktrees can share the hook without running each
other's binaries. The hook does not build Atmos during a commit.

When installed by a system binary, the shim retains that absolute path as a fallback
for GUI clients, and uses `PATH` if that binary has moved or been removed.

## Examples

```shell
# Install all hooks configured under git.hooks
atmos git hooks install

# Install only specific hooks
atmos git hooks install pre-commit commit-msg

# Back up and replace a hook generated by the pre-commit framework
atmos git hooks install pre-commit --force

# Overwrite existing hooks
atmos git hooks install --force
```

## Behavior

- Installs **all** configured hooks when no hook names are provided; only the requested hooks otherwise.
- Validates each hook before writing its shim: exactly one of `command` or `steps` must be set, and a `steps` list must be a valid step list. An invalid hook fails the install.
- Warns for names under `git.hooks` that are not Git hook names, because Git never runs such a hook.
- Reports shims that are already installed when you re-run the command.
- **Refuses to overwrite** a custom hook unless `--force` is passed. Existing Atmos shims can be updated without it.
- Marks generated shim scripts executable.
- Resolves the hooks directory through Git (`git rev-parse --git-path hooks`), so linked worktrees — where `.git` is a file and hooks live in the common dir — work correctly.
- Refuses installation when `core.hooksPath` is configured (for example, by Husky), even with `--force`, preserving the configured hook directory and its files. Reconcile the existing hook manager and setting before installing Atmos hooks.

With `--force`, recognized pre-commit-framework shims are backed up
alongside the old hook before replacement. The `--force` flag also permits overwriting unrelated custom hooks, so inspect
the existing hook before using it. Reconcile any `core.hooksPath` configuration
explicitly. Linked worktrees can share the hooks
directory; prepare each worktree's binaries before using a shared shim. Replacing a launcher
does not convert `.pre-commit-config.yaml`, install tools, or build check binaries.

:::note PATH and GUI Git clients

A local worktree build takes precedence. Shims installed by a system binary retain
its absolute path as a fallback when a GUI client's `PATH` omits Atmos. Shims
installed from `build/atmos` require either the current worktree's build or `atmos`
on the client's `PATH`.

Run `atmos git hooks install` again to upgrade an existing Atmos shim to this
worktree-aware launcher. Existing Atmos shims are updated without `--force`.

:::

## Arguments

- **`hook-name...` (optional)** — One or more Git hook names (`pre-commit`, `commit-msg`, `pre-push`, ...) to install. When omitted, all hooks configured under `git.hooks` are installed.

## Flags

- **`--force` / `-f` (optional)** — Overwrite existing custom hook scripts. Existing Atmos shims can be updated without it.
  Recognized pre-commit-generated hooks are backed up before replacement.
  Environment variable: `ATMOS_GIT_HOOKS_FORCE`

## Related

- [`atmos git hooks run`](/cli/commands/git/hooks/run) — what the generated shims execute
- [`atmos git hooks uninstall`](/cli/commands/git/hooks/uninstall) — remove Atmos-generated shims
- [Git Configuration](/cli/configuration/git#local-git-hooks) — the `git.hooks` section