Skip to main content

atmos git hooks install

Write local .git/hooks/<hook> shim scripts for the hooks configured under 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.

atmos git hooks install --help

Usage​

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

Given this configuration:

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​

# 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.

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​