API Reference

This page contains the API reference for bun-git-hooks. It documents all the types, interfaces, and configurations available in the package.

Configuration Types

GitHooksConfig

The main configuration type for the package. It defines the structure of your git hooks configuration.

type GitHooksConfig = {
  // Git hook configurations
  [hookName in GitHook]?: string | {
    stagedLint?: StagedLintConfig
  }
} & {
  // Global options
  preserveUnused?: boolean | GitHook[]
  verbose?: boolean
  stagedLint?: StagedLintConfig
}

Properties

• [hookName]: Configuration for individual git hooks

  • Type: string | { stagedLint?: StagedLintConfig }
  • Optional
  • Example: 'preCommit': 'bun run lint'

• preserveUnused

  • Type: boolean | GitHook[]
  • Optional
  • Description: Specifies which hooks should not be managed by bun-git-hooks
  • Example: preserveUnused: ['post-checkout', 'post-merge']

• verbose

  • Type: boolean
  • Optional
  • Description: Enables verbose logging
  • Default: false

• stagedLint

  • Type: StagedLintConfig
  • Optional
  • Description: Global staged linting configuration

StagedLintConfig

Configuration for staged file linting.

interface StagedLintConfig {
  [pattern: string]: StagedLintTask
}

type StagedLintTask = string | string[]

Pattern Properties

• [pattern]: Git-style glob pattern for matching files
  • Type: string | string[]
  • Description: Command(s) to run on matched files
  • Example: '*.ts': 'eslint --fix'

Supported Git Hooks

The following Git hooks are supported:

• preCommit: Run before committing (supports stagedLint)
• prepareCommitMsg: Run before the commit message editor is opened
• commitMsg: Run to verify commit message
• postCommit: Run after committing
• prePush: Run before pushing
• postCheckout: Run after checking out a branch
• preRebase: Run before rebasing
• postMerge: Run after merging
• postRewrite: Run after commands that rewrite commits
• preAutoGc: Run before garbage collection

Environment Variables

Configuration Variables

• SKIP_BUN_GIT_HOOKS

  • Type: string
  • Description: Skip hook execution when set to "1"
  • Example: SKIP_BUN_GIT_HOOKS=1 git commit -m "quick fix"

• BUN_GIT_HOOKS_RC

  • Type: string
  • Description: Path to custom initialization script
  • Example: BUN_GIT_HOOKS_RC=/path/to/init.sh

• SKIP_INSTALL_GIT_HOOKS

  • Type: string
  • Description: Skip hook installation when set to "1"
  • Example: SKIP_INSTALL_GIT_HOOKS=1 bun install

Configuration File

The configuration can be defined in any of these files:

git-hooks.config.ts    # TypeScript (recommended)
git-hooks.config.js    # JavaScript
git-hooks.config.mjs   # ES Modules
git-hooks.config.cjs   # CommonJS
git-hooks.config.json  # JSON

Or in package.json:

{
  "git-hooks": {
    "preCommit": "bun run lint"
  }
}

Examples

Basic Configuration

const config: GitHooksConfig = {
  preCommit: 'bun run lint',
  commitMsg: 'bun commitlint --edit $1',
  prePush: 'bun run test'
}

Advanced Configuration with Staged Linting

const config: GitHooksConfig = {
  preCommit: {
    stagedLint: {
      '*.{js,ts}': ['eslint --fix', 'prettier --write'],
      '*.{css,scss}': 'stylelint --fix'
    }
  },
  verbose: true,
  preserveUnused: ['postCheckout']
}

Dynamic Configuration

const config: GitHooksConfig = {
  preCommit: process.env.CI
    ? 'bun run test:ci'
    : {
        stagedLint: {
          '*.ts': 'eslint --fix'
        }
      },
  verbose: !process.env.CI
}