Skip to content
GitPersonaGitPersona

Commit Guard

Commit Guard is the final safety layer. It installs a managed pre-commit hook that checks the Git identity a commit would use against the profile the repository is expected to commit as, and warns — or blocks — on a mismatch.

What it protects

Commit Guard verifies, at the moment you commit, that the repository's current user.name and user.email match the identity of its expected profile. It is opt-in and disabled by default.

Note: Commit Guard verifies the Git author name and email only. It does not validate SSH keys, GPG signatures, remote authorization, or credentials — keeping the check fast, reliable, and offline.

Commit Guard vs Smart Switching

These are two complementary mechanisms — not duplicates:

  • Smart Switching is proactive: it applies the correct profile automatically as you move between repositories, so the right identity is active before you commit.
  • Commit Guard is a verification: it checks the identity at commit time and catches a mismatch — whether Smart Switching is off, a repository has no rule or assignment, or an identity was changed by hand.

Run both together for defense in depth: Smart Switching keeps the identity correct; Commit Guard confirms it right before the commit is written.

Warn vs block

  • Warn (default) — prints a clear warning showing the expected and current identity, then lets the commit proceed.
  • Block — aborts the commit on a mismatch. You switch to the correct profile and commit again.

How the expected profile is resolved

Commit Guard reuses the same resolution as switching: a matching rulewins, otherwise the repository's direct assignment. The resolved profile's name and email are written into the repository's local Git config as the expected identity for the hook to compare against.

Note: Fallback: if no expected profile can be resolved (no rule matches and the repository is unassigned), Commit Guard allows the commit. It never blocks on the unknown.

Protecting a repository

  1. Enable Commit Guard in Settings and choose the default mode (warn or block).
  2. Protect repositories individually from the Commit Guard list, or turn on Auto-protect assigned repositories to install the hook automatically whenever a profile is assigned.
  3. The Settings view shows each repository's protection state, its expected profile, and whether the current identity matches.

Disabling Commit Guard removes the managed hooks again (restoring any hook that was chained). Individual repositories can be protected or removed at any time.

Existing hook compatibility

Installation is non-destructive. If a repository already has a pre-commithook that GitPersona didn't create, that hook is backed up and chained — the managed hook runs your original first and only proceeds if it succeeds. Removing Commit Guard restores the original hook.

Warning: If a repository routes hooks through a custom core.hooksPath, GitPersona reports it as unsupported rather than installing a hook that Git would ignore. Set up the check manually in that case.

Overriding a block

When a commit is blocked and you intend it anyway, bypass the hook for a single commit with Git's standard flag:

git
git commit --no-verify -m "..."

Troubleshooting

  • The hook doesn't run— confirm the repository isn't using core.hooksPath, and that Commit Guard is enabled and the repository is protected.
  • Unexpected mismatch warnings— check the repository's expected profile and that the active identity matches; the Settings list shows both.
  • A hook looks stale after reassigning — use Repair to rewrite the managed hook and refresh the expected identity.