hav Commit Guard

hav Commit Guard is a VS Code quality gate for staged Git changes.

It scans staged changes before you commit, reporting unresolved TODOs, debug leftovers, merge conflict markers, and matches from custom regex rules.

Table of Contents

• Features
• Screenshots
• Default rules
• Commands
• VS Code settings
• Rule format
• Repository hook config
• Commit blocking
• Build from source
• Contributing
• License

Features

• Scans staged Git changes
• Shows findings in the Problems view
• Shows issue counts in the Status Bar
• Opens issues from a Quick Pick
• Automatically rescans when Git state changes
• Falls back to debounced rescans on file save
• Adds Source Control view title buttons for hook install/remove and one-time bypass/clear
• Can install or remove an optional Git pre-commit hook to block commits with errors
• Can arm or clear a one-time VS Code bypass for the next commit
• English and German messages for the UI and hook CLI
• Configurable rules
• Repository-level hook configuration via .hav-commit-guard.json

Screenshots

Find errors and warnings in staged changes.

Block commits when staged errors are found.

Jump directly to staged issues.

Default rules

Commands

• hav Commit Guard: Scan Staged Changes
• hav Commit Guard: Show Issues
• hav Commit Guard: Bypass Next Commit Once
• hav Commit Guard: Clear Next Commit Bypass
• hav Commit Guard: Install Git Hook
• hav Commit Guard: Remove Git Hook

When a Git repository is open, the Source Control view also shows compact buttons for these repository actions:

• Install Git Hook, replaced by Remove Git Hook after this extension's hook is installed
• Bypass Next Commit Once, replaced by Clear Next Commit Bypass while the bypass is armed

VS Code settings

{
  "havCommitGuard.autoScan": true,
  "havCommitGuard.debounceMs": 250,
  "havCommitGuard.maxFileSizeKb": 512,
  "havCommitGuard.rules": [
    {
      "id": "todo",
      "label": "TODO comment",
      "pattern": "\\bTODO\\b:?(.*)",
      "severity": "warning",
      "filePattern": "\\.(js|jsx|ts|tsx|vue|svelte|c|cc|cpp|cxx|h|hpp|hh|hxx|cs|csx|py|rb|php|go|rs|java|kt|swift|m|mm|scala|sh|bash|zsh|ps1)$"
    },
    {
      "id": "fixme",
      "label": "FIXME comment",
      "pattern": "\\bFIXME\\b:?(.*)",
      "severity": "error",
      "filePattern": "\\.(js|jsx|ts|tsx|vue|svelte|c|cc|cpp|cxx|h|hpp|hh|hxx|cs|csx|py|rb|php|go|rs|java|kt|swift|m|mm|scala|sh|bash|zsh|ps1)$"
    },
    {
      "id": "hack",
      "label": "HACK comment",
      "pattern": "\\bHACK\\b:?(.*)",
      "severity": "error",
      "filePattern": "\\.(js|jsx|ts|tsx|vue|svelte|c|cc|cpp|cxx|h|hpp|hh|hxx|cs|csx|py|rb|php|go|rs|java|kt|swift|m|mm|scala|sh|bash|zsh|ps1)$"
    }
  ]
}

NOTE: By default, TODO/FIXME/HACK rules apply only to code-like files. Non-code files are ignored unless a matching filePattern includes them.

Rule format

interface havCommitGuardRule {
  id: string;
  label?: string;
  pattern: string;
  severity: "off" | "warning" | "error";
  filePattern?: string;
}

pattern and filePattern are JavaScript regular expressions.

Repository hook config

The Git hook runs outside VS Code, so it uses the default rules unless the repository includes this file:

.hav-commit-guard.json

Use .hav-commit-guard.example.json as a starting point.

Commit blocking

Errors block commits when the Git hook is installed. Warnings are reported and do not block.

Use hav Commit Guard: Install Git Hook to enable commit blocking for a repository, and hav Commit Guard: Remove Git Hook to disable it again. These commands are available from the Command Palette and as a stateful button in the Source Control view.

Git hook installation respects Git's core.hooksPath. If it is not configured, the extension uses the repository's default .git/hooks/pre-commit.

In restricted or untrusted workspaces, staged-change scanning remains available, but installing or removing the Git hook and changing bypass state require trusting the workspace.

For a deliberate one-time bypass, use:

• hav Commit Guard: Bypass Next Commit Once (recommended in VS Code)
• or git commit --no-verify (fallback)

The VS Code bypass is single-use and is consumed by the next commit attempt in that repository.

Use hav Commit Guard: Clear Next Commit Bypass to cancel an armed bypass before committing. The Source Control view bypass button switches to the clear button while the bypass is armed.

Terminal fallback:

git commit --no-verify

Build from source

git clone https://github.com/Havoc7891/hav-commit-guard.git
cd hav-commit-guard

npm install
npm run compile
npm run package

NOTE: The VSIX package is written to the repository root.

Contributing

Thank you for your interest! Suggestions for features and bug reports are always welcome via issues.

To maintain a consistent design and quality for this extension, changes are implemented by the maintainer rather than via direct pull requests.

License

This extension is licensed under the MIT License.