gabyx-githooks-setup

name	gabyx-githooks-setup
description	Set up shared Git hooks using gabyx/Githooks (not standard git hooks). Use when a user asks to set up githooks, apply shared hooks, or configure hook repositories in a project.
autouse	false

Githooks Setup (gabyx/Githooks)

Set up and configure shared Git hooks using the gabyx/Githooks manager. This is not the standard git config core.hooksPath system — it is a dedicated hooks manager that supports shared hook repositories, parallel execution, trust verification, and more.

Important

The git hooks CLI (note the space) is provided by gabyx/Githooks. Do not confuse it with standard git hook configuration.

Instructions

0. Verify Githooks is installed

Before proceeding, check whether gabyx/Githooks is installed:

git hooks --version 2>/dev/null

If this command fails or is not found, Githooks is not installed. Refer to INSTALL.md in this skill directory for installation methods, then return here to continue setup.

1. Determine the user's intent

Ask which setup the user wants:

• Global shared hooks — A shared hook repository is already registered in the global Githooks configuration. Just activate Githooks in the current repo.
• Repo-specific shared hooks — Add a .githooks/.shared.yaml file so the repo pulls hooks from a specific shared repository, independent of the user's global config.

If the user doesn't already have a shared hook repository in mind, ask if they'd like to use jaeyeom/shared-githooks (authored by the same person who wrote this plugin). It includes pre-commit checks (whitespace, non-ASCII filenames, Go linting) and commit-msg checks (subject length, conventional format). The user should review its contents before opting in.

2. Global shared hooks (already configured globally)

When the shared hook repository is already in the global list (git config --global --get-all githooks.shared), all you need is:

git hooks install

This activates Githooks in the current repository. It rewires .git/hooks to the Githooks runner, which then discovers and executes both local (.githooks/) and globally-configured shared hooks.

Then enable the non-interactive runner globally (one-time per user):

git hooks config non-interactive-runner --enable --global

This makes the runner auto-answer non-fatal prompts with sensible defaults instead of falling back to a blocking GUI dialog when no terminal is attached (the typical case for git commit --amend --no-edit, editor integrations, and CI). The trust prompt remains fatal — see section 6.

After installation, check for replaced hooks (see section 2a below), then update shared hooks:

git hooks shared update

Verify with:

git hooks list

2a. Check for replaced hooks

When git hooks install finds existing hook scripts in .git/hooks/, it renames them to *.replaced.githook (e.g., pre-commit → pre-commit.replaced.githook). The Githooks runner executes these in addition to shared hooks, which causes duplicate checks if the shared hooks already cover the same functionality.

After running git hooks install, check for replaced hooks:

ls .git/hooks/*.replaced.githook 2>/dev/null

If any are found:

1. List them to the user and explain that these are pre-existing hook scripts that Githooks renamed and will continue to execute alongside shared hooks.
2. Recommend removal if the shared hooks repository already covers the same hook types (e.g., if shared hooks include pre-commit checks and there is a pre-commit.replaced.githook, the pre-commit checks will run twice). Provide the specific rm commands, for example:

rm .git/hooks/pre-commit.replaced.githook
rm .git/hooks/commit-msg.replaced.githook
rm .git/hooks/pre-push.replaced.githook

3. If the user is unsure whether the replaced hooks are redundant, suggest running git hooks list to see all hooks that will execute, and comparing the replaced hook contents against the shared hooks.

3. Repo-specific shared hooks

To configure a shared hook repository for a single repo without depending on global config:

1. Create the shared config file (replace the URL with the chosen shared hook repository):

# .githooks/.shared.yaml
version: 1
urls:
  - "https://github.com/<owner>/<shared-hooks-repo>.git@main"

2. Install Githooks in the repo (if not already active):

git hooks install

3. Enable the non-interactive runner globally (one-time per user):

git hooks config non-interactive-runner --enable --global

This auto-answers non-fatal prompts with sensible defaults so hooks never block on a GUI dialog when no terminal is attached. The trust prompt stays fatal — see section 6.

4. Check for replaced hooks (see section 2a above) and remove any that are redundant with the shared hooks.

5. Pull the shared hooks:

git hooks shared update

6. Commit .githooks/.shared.yaml so other contributors get the same hooks.

4. Useful commands

Command	Purpose
git hooks install	Activate Githooks in current repo
git hooks uninstall	Remove Githooks from current repo
git hooks shared update	Pull latest shared hook repositories
git hooks list	Show all hooks that will run and their status
git hooks config	Manage Githooks settings
git hooks ignore add	Exclude specific hooks by pattern
git hooks shared root ns:<namespace>	Show shared repo root for a namespace

5. Updating shared hooks

Shared hook repositories update automatically after post-merge (i.e., git pull). To update manually:

git hooks shared update

This pulls the latest from all configured shared hook repositories (both global and repo-specific). Run this after upstream hooks are updated to get fixes.

Note: git hooks shared update only updates shared hooks. Local hooks in the repo's own .githooks/ directory are part of the repo itself and are updated via normal git pull/git checkout.

On servers with multiple users, disable automatic updates to avoid parallel invocations:

git hooks config disable-shared-hooks-update --set

6. Trust handling

Githooks verifies hook checksums. When new or modified hooks are detected, it prompts for trust confirmation — and unlike other prompts, the trust prompt is fatal under the non-interactive runner enabled in steps 2 and 3. That is intentional: a hard failure tells the user a trust decision is required, instead of silently popping a GUI dialog or hanging a script.

To resolve a trust failure, trust hooks selectively by namespace.

Trusting a specific shared hook repository (recommended):

Each shared hook repo has a namespace (defined in .githooks/.namespace, or a SHA1 prefix of its URL if not set). Use git hooks list to see namespace paths, then trust by pattern:

# See namespace paths for all hooks
git hooks list

# Trust all hooks from a specific shared repo by namespace
git hooks trust hooks --pattern "ns:jaeyeom-shared-githooks/**"

This is safer than trust-all because it only trusts hooks from a known, authored source. When the shared repo updates, you may need to re-run this command to trust the new checksums.

Other trust options:

Method	Scope	Effect
git hooks trust hooks --pattern "ns:<namespace>/**"	Per-repo, per-user	Trusts hooks matching a namespace pattern — preferred approach
git hooks trust hooks --all	Per-repo, per-user	Trusts all currently active hooks
git hooks trust	Per-repo, per-user	Marks repo as trusted for the current user (each collaborator should run this locally)
.githooks/trust-all file	Per-repo	Marks repo as trusted — do not commit this file; add it to .gitignore instead, as trust is a per-user security decision
git hooks config trust-all --accept	Per-repo	Auto-accepts all current and future hooks (use with caution — prefer namespace-based trust instead)
git hooks config trust-all --reset	Per-repo	Reverts trust-all decision
GITHOOKS_SKIP_UNTRUSTED_HOOKS=true	Per-session	Skips untrusted hooks silently
GITHOOKS_DISABLE=1	Per-session	Disables all Githooks entirely

For CI/automation, either set GITHOOKS_DISABLE=1 to skip hooks entirely, or use trust-all --accept so the runner auto-trusts hooks (the non-interactive runner from initial setup already handles non-fatal prompts).

6a. Shared trust DB across many repos

When a user maintains many repos that all consume the same shared hook repository, the per-repo trust model becomes painful:

• Each new clone requires git hooks trust hooks --pattern "ns:<namespace>/**".
• Every upstream update to the shared hook content invalidates the checksum and forces re-trusting in every repo.
• This pushes users toward trust-all (security-coarse) or GITHOOKS_SKIP_UNTRUSTED_HOOKS (security-off) just to keep ergonomic defaults.

The trust database lives at .git/.githooks.checksums/<sha[:2]>/<sha[2:]> and is content-addressed by SHA. Each entry's stored path: field is decorative — the runner only does a SHA lookup. Pointing every repo's .git/.githooks.checksums at a single global directory therefore makes trust granted in one repo apply to every symlinked repo.

One-time setup per repo:

mkdir -p ~/.githooks/checksums-global
[ -d .git/.githooks.checksums ] && \
  cp -R .git/.githooks.checksums/. ~/.githooks/checksums-global/ && \
  rm -rf .git/.githooks.checksums
ln -s ~/.githooks/checksums-global .git/.githooks.checksums

After this, running git hooks trust hooks --pattern "ns:<namespace>/**" in any one repo immediately applies to all symlinked repos. A fresh clone with zero local checksums correctly inherits trust through the symlink — no prompts, hooks run normally.

Caveats:

• The trust DB format is undocumented internal state. If gabyx changes it (JSON, sqlite, etc.) the symlinks will silently break.
• Local-hook SHA collisions across repos overwrite the (cosmetic) path: field — harmless but worth noting.
• git clone and git init rebuild .git/, so the symlink must be reinstated on every new clone (a wrapper around git clone can automate this).
• This widens trust scope from per-repo to per-user. It does not weaken the SHA-based content check itself — the same security primitive applies more broadly. Continue to trust selectively (namespace patterns, not --all).

Upstream tracking: A proper fix (user-scoped trust store with diff-gated re-trust) is requested at gabyx/Githooks#200 but is not yet implemented.

7. Shared hook repository structure

Shared repos organize hooks as:

<repo>/.githooks/<hook-type>/<script>

For example:

.githooks/pre-commit/format-check.sh
.githooks/commit-msg/conventional-commits.sh

Each shared repo can declare a namespace via .githooks/.namespace to avoid naming conflicts.