git-hygiene 🌊

The ultimate zero-dependency metadata validator for modern Git workflows.

Features • Installation • Usage • Architecture • Contributing

git-hygiene is a high-performance, zero-dependency engine designed to enforce perfect metadata across your entire Git lifecycle. Built for Node.js 24+, it leverages native TypeScript type-stripping for microsecond startup times and zero-compilation runtime performance.

# Using pnpm (Recommended)
pnpm add -D @chitrank2050/git-hygiene

# Using JSR (For Deno / Modern Node)
npx jsr add @chitrank2050/git-hygiene

# Using npm
npm install --save-dev @chitrank2050/git-hygiene

The recommended way to use git-hygiene locally.

# lefthook.yml
commit-msg:
  commands:
    hygiene:
      run: npx @chitrank2050/git-hygiene commit {1}

pre-push:
  commands:
    hygiene:
      run: npx @chitrank2050/git-hygiene branch

For projects using Husky 9+.

# .husky/commit-msg
npx @chitrank2050/git-hygiene commit $1

# .husky/pre-push
npx @chitrank2050/git-hygiene branch

Validate your metadata natively in CI. We recommend pinning to a specific SHA.

Just drop the action into your PR workflow. It will automatically detect the context, validate your PR title and branch name, and suggest a version bump.

- name: Git Hygiene 🌊
  uses: chitranklabs/git-hygiene@8abac926a6afcde68889b34f9ec3d1acefd69538

For granular control over specific commands.

# Validate PR Title explicitly
- name: Validate PR Title 🏷️
  uses: chitranklabs/git-hygiene@8abac926a6afcde68889b34f9ec3d1acefd69538
  with:
    command: 'title'
    value: '${{ github.event.pull_request.title }}'

# Validate Branch Name
- name: Validate Branch Name 🌿
  uses: chitranklabs/git-hygiene@8abac926a6afcde68889b34f9ec3d1acefd69538
  with:
    command: 'branch'
    value: '${{ github.head_ref }}'

Run any check manually from the terminal.

# Check a specific commit message
npx @chitrank2050/git-hygiene commit "feat: my awesome commit"

# Check a branch name string
npx @chitrank2050/git-hygiene branch "feature/cool-stuff"

# Check a PR title
npx @chitrank2050/git-hygiene title "fix(core): resolve memory leak"

# Suggest the next semantic version bump
npx @chitrank2050/git-hygiene bump

# Output result as JSON (useful for automation)
npx @chitrank2050/git-hygiene bump --json

You can easily integrate git-hygiene into your CI/CD pipeline using the official GitHub Action. This allows you to validate PR titles, branch names, and commit messages automatically.

jobs:
  hygiene:
    runs-on: ubuntu-latest
    steps:
      - name: Validate PR Title 🌊
        id: hygiene
        uses: chitranklabs/git-hygiene@8abac926a6afcde68889b34f9ec3d1acefd69538
        with:
          command: 'title'
          value: ${{ github.event.pull_request.title }}

### Action Outputs 📤

When using the `bump` command, the action provides the following outputs:

| Output        | Description                                     |
| ------------- | ----------------------------------------------- |
| `releaseType` | Recommended bump (`patch`, `minor`, or `major`) |
| `reason`      | Explanation for the recommendation              |

```yaml
- name: Get Bump 🚀
  id: bump
  uses: chitranklabs/git-hygiene@8abac926a6afcde68889b34f9ec3d1acefd69538
  with:
    command: 'bump'

- name: Tag Release 🏷️
  run: echo "Next version is ${{ steps.bump.outputs.releaseType }}"

Note on Pinning to a SHA: For maximum security and stability, we highly recommend pinning the uses directive to a specific commit SHA instead of a branch like @main. You can get the commit SHA by navigating to the Commits page of this repository and copying the 40-character hash (e.g. uses: chitranklabs/git-hygiene@8f3d...).

Import the engine directly into your TypeScript project.

import { validateBranch, resolveConfig } from '@chitrank2050/git-hygiene-core';

// Standard usage (auto-loads package.json)
const { valid } = await validateBranch('feat/new-ui');

// Programmatic usage with config override
const customConfig = await resolveConfig({ types: ['feat', 'fix'] });
const result = await validateBranch('feat/new-ui', customConfig);

git-hygiene isn't just a validator-it's a release companion. You can use its outputs to automate your entire versioning pipeline. Check out our own release-prepare.yml to see how we use the bump output to automate version increments.

git-hygiene is designed to be zero-config, but you can easily customize the engine by adding a git-hygiene block to your root package.json.

{
  "git-hygiene": {
    "extends": ["@commitlint/config-conventional"],
    "types": ["feat", "fix", "chore", "docs", "refactor", "test", "renovate"],
    "ignoreBranches": ["main", "develop", "release/*"],
    "maxHeaderLength": 100,
    "allowEmptyScope": false,
    "rules": {
      "subject-case": [2, "always", "sentence-case"],
      "header-max-length": [2, "always", 72]
    }
  }
}

git-hygiene now supports extending standard configurations. The most common use case is extending @commitlint/config-conventional to inherit the industry-standard types and rules.

When you extend a configuration:

• Types are merged: Your local types are combined with the types from the extended config.
• Rules are inherited: Standard rules (like header-max-length) are automatically applied.
• Parser Presets: Advanced syntax (like the ! breaking change indicator) is automatically supported.

For power users, the rules property allows you to pass any raw commitlint rule directly to the underlying engine. This gives you full control over every aspect of your commit validation.

"rules": {
  "body-leading-blank": [2, "always"],
  "footer-leading-blank": [1, "always"]
}

graph TD
    A[Consumer Project] -->|CLI| B["@chitrank2050/git-hygiene"]
    A -->|Action| C["GitHub Action (Root)"]
    B --> D["@chitrank2050/git-hygiene-core"]
    C --> D
    D -->|Engine| E["Conventional Commits & Regex"]

git-hygiene stands on the shoulders of giants. Special thanks to:

• commitlint: For the industry-standard commit validation logic we use under the hood.

We ❤️ contributions! Whether you're fixing a bug, adding a feature, or improving documentation, please see our Contributing Guide to get started.

• Security: Please see our Security Policy for reporting vulnerabilities.
• Conduct: We follow the Contributor Covenant Code of Conduct.
• Support: If you use git-hygiene in your project, a star or credit is appreciated. ✨

• Secret Scanning: Gitleaks prevents credential leaks in every commit.
• Workflow Auditing: Zizmor ensures GitHub Actions follow security best practices.
• Supply Chain: All GitHub Actions are pinned to secure commit SHAs.
• Provenace: Automated build attestations for every release.

Developed with ❤️ by Chitrank Agnihotri

If you use this in your project, a credit or star is appreciated. ✨