blog.dopana

Back

Ensuring consistent code formatting and clean documentation before committing to Git is essential for maintainable projects. Instead of relying on bulky third-party tools, you can leverage native Git Hooks with core.hooksPath for a lightweight, zero-dependency pre-commit pipeline.

Files foundNoneFiles foundNoneFiles foundNoneSyntax ErrorValidDeveloper runs git commit -m'...'.githooks/pre-commit triggered1. Check staged Markdown(.md, .mdx)Run agent-md formatand git add file2. Check staged Code(.ts, .tsx, .astro...)Run bun lint (ESLint)and git add file3. Check stagedDocs/DiagramsRun bun lint:mermaid (maid)Commit Successful ✅Commit Aborted ❌Fix syntax before committing

Why Native Git Hooks Over Husky?#

Native Git Hook (core.hooksPath)Husky ApproachRequires npm packageinstallationBloats node_modulesDepends on external Node.jswrappersSingle shell script in .githooks/Zero external dependenciesVersion controlled across team
FeatureHusky / Third-partyNative Git Hook (core.hooksPath)
DependenciesRequires npm packagesZero dependencies
Execution SpeedNode wrapper startup overheadInstant Shell execution (<10ms)
Git SharedYesYes (committed inside repository)

Complete Pre-commit Hook Script#

Place this script at .githooks/pre-commit:

Detailed Logic Breakdown#

1. Staged Files Filtering via git diff --cached#

Git Index (Staged Area)git diff --cached --name-only--diff-filter=dgrep -E '\\.(ext)$'Target list of files
  • --cached: Restricts checks strictly to staged files ready to be committed.
  • --diff-filter=d: Excludes deleted files so linters don’t throw errors trying to open missing files.
  • set -e: Halts execution and aborts the commit if any linter exits with non-zero status.

2. Automated Re-staging#

Whenever formatting tools (agent-md or eslint --fix) adjust staged files, git add "$file" bundles the fixes directly into the current commit.

Setting Up Repository Automation#

Add the prepare script in package.json:

{
  "scripts": {
    "prepare": "git config core.hooksPath .githooks",
    "lint": "eslint --fix 'src/**/*.{js,ts,jsx,tsx,astro}'",
    "lint:mermaid": "maid docs/ src/"
  }
}
json

Make the script executable:

chmod +x .githooks/pre-commit
bun run prepare
bash

When teammates install dependencies via bun install, the prepare script runs automatically and activates the hook path.

Conclusion#

With a clean shell script:

  • All Markdown files stay neatly formatted.
  • Source code is automatically linted.
  • Mermaid diagrams are verified to prevent broken documentation.

References#