@bstopp/git-who 0.2.0 → 0.3.0

package/README.md

@@ -70,12 +70,17 @@ exist, you get a warning and the same prompt.
 | `git who list` | List all profiles with their SSH hosts. The profile active in the current repo is in bold. |
 | `git who show [name]` | Show a profile. With no name, show the profile for the current repo. |
 | `git who use [name]` | Apply a profile to the current repo. |
+| `git who check` | Fail if the current repo's git config doesn't match its profile. |
+| `git who hook install` | Run `check` before every commit in the current repo. See [Pre-commit hook](#pre-commit-hook). |
+| `git who hook uninstall` | Stop running `check` before commits in the current repo. |
 | `git who clone <repo> [name]` | Clone a repo using a profile, then apply the profile to the clone. |
 | `git who edit [name]` | Edit a profile. The prompts are pre-filled with the current values. |
 | `git who remove [name]` | Remove a profile, after confirmation. |
 
 Run `git who --help` for usage and `git who --version` for the version.
 
+`list`, `show`, `use` and `check` also take `--json`, for scripts and AI agents. See [JSON output](#json-output).
+
 ### `add`
 
 Prompts for, in order:
@@ -88,6 +93,45 @@ Prompts for, in order:
      directly. The identity's name and email become the defaults for the next two prompts.
 4. **Git `user.name`** and **`user.email`**.
 
+### `check`
+
+Checks the current repo's git config against its profile (the one named by `gitwho.profile`, or the one matching
+`user.name` and `user.email`) and exits non-zero if they differ. It compares `user.name`, `user.email`, `user.signingKey`
+and whether commits are signed, and the error names each setting that differs. It prints nothing when the repo matches,
+and never prompts.
+
+To stop a commit made under the wrong identity, run it before every commit with a
+[pre-commit hook](#pre-commit-hook). A repo with no profile, or whose identity matches none, fails the check too.
+
+### Pre-commit hook
+
+`git who hook install` makes git run `git who check` before every commit in the current repo, and a commit under the
+wrong identity is refused with the settings that differ. `git who hook uninstall` takes it out again. Both only touch the
+repo's local git config.
+
+It uses git's config hooks (`hook.git-who.command` and `hook.git-who.event`), not a file in `.git/hooks`, so it runs
+alongside any `pre-commit` hook the repo already has and never overwrites it. It needs a git recent enough to have them.
+After installing, `git who` checks that `git hook list pre-commit` shows the hook, and if it doesn't it removes the
+config again and tells you, rather than leaving a hook that never runs.
+
+To do the same by hand:
+
+```
+git config --local hook.git-who.command 'git who check'
+git config --local hook.git-who.event pre-commit
+```
+
+If you use [husky](https://typicode.github.io/husky), the hook above works with it as is. Or put the command in husky's
+own hook instead, by adding this line to `.husky/pre-commit`:
+
+```
+git who check
+```
+
+`git commit --no-verify` skips the hook, because git skips `pre-commit` hooks with it. The hook is a guard against
+forgetting to switch profiles, not something that enforces it. It also fails the commit if `git who` isn't on the
+`PATH`, such as after uninstalling the tool without running `git who hook uninstall`.
+
 ### `use`
 
 Applies a profile to the current repo by writing to its **local** git config:
@@ -167,6 +211,78 @@ Shows the profile and asks for confirmation. If the profile is the active one in
 time and its `gitwho.profile` is cleared from that repo afterwards. Other repos that still name the removed profile are
 not touched.
 
+## JSON output
+
+`list`, `show`, `use` and `check` take `--json`, which prints the result as JSON on stdout so a script or an AI agent can read it.
+With `--json` nothing is printed except the JSON: no blank lines, no colors, and no warnings on stderr. What a warning
+would have said is a field in the output instead.
+
+`add`, `edit` and `remove` are interactive and do not take `--json`.
+
+| Command | Output |
+| --- | --- |
+| `git who list --json` | An array of profiles. Each has the profile's fields and `active`, true for the profile in use in the current repo. |
+| `git who show [name] --json` | `{ profile, derived, signingKeyStatus, mismatches }` |
+| `git who use <name> --json` | `{ profile, originUpdated, origin }` |
+| `git who check --json` | `{ profile, derived }` when the repo matches its profile. A mismatch is an error, like any other failure. |
+
+A field with no value is left out of the object. `signingMethod` and `signingKey` are absent for a profile that doesn't
+sign.
+
+```
+$ git who show --json
+{
+  "profile": {
+    "name": "work",
+    "host": "github-work",
+    "username": "Bryan Work",
+    "email": "bryan@work.com",
+    "signingMethod": "ssh",
+    "signingKey": "/Users/bryan/.ssh/id_work.pub"
+  },
+  "derived": false,
+  "signingKeyStatus": { "found": true },
+  "mismatches": { "email": "bryan@personal.com" }
+}
+```
+
+- **`derived`** is true when the profile was matched from the repo's `user.name` and `user.email`, not named by
+  `gitwho.profile`.
+- **`signingKeyStatus`** is only present for a profile that signs. `found` is false when the key isn't on this machine.
+  For GPG, `uids` lists the identities on the key.
+- **`mismatches`** is only present when the profile comes from the repo (`show` with no name). It lists the fields where
+  the repo's git config differs from the profile, with the value git has. `null` means git has nothing set. An empty
+  object means the repo matches the profile.
+
+### `use --json`
+
+`use --json` never prompts, so it needs a profile name and fails without one. The prompt for a mismatched `origin` is
+replaced by a flag:
+
+- Without `--update-origin`, `origin` is left alone. If it doesn't use the profile's SSH host, the output has
+  `origin: { current, expected }` and `originUpdated` is false.
+- With `--update-origin`, `origin` is rewritten to `expected` and `originUpdated` is true.
+
+`--update-origin` also works without `--json`, where it answers yes to the prompt.
+
+### Errors
+
+With `--json`, a failure is printed as JSON on stdout and the exit code is still `1`:
+
+```
+{
+  "error": "Failed to apply profile 'work'. Git config may be partly updated; re-run to retry.",
+  "causes": ["addConfig failed"]
+}
+```
+
+`causes` holds the messages of the wrapped errors, outermost first, and is empty when there are none.
+
+### Agent skill
+
+The package includes a skill that teaches an AI agent to use these commands: `skills/git-who/SKILL.md`, in the installed
+package. Copy or link the `git-who` folder into your agent's skills directory (for Claude Code, `~/.claude/skills/`).
+
 ## Where profiles are stored
 
 Profiles live in `~/.git-who.cfg.json`, as a JSON array. You can edit it by hand, but `git who` validates it on every

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@bstopp/git-who",
-    "version": "0.2.0",
+    "version": "0.3.0",
     "type": "module",
     "description": "Manage git profiles for per-project SSH account configuration.",
     "license": "Apache-2.0",
@@ -19,7 +19,8 @@
         "access": "public"
     },
     "files": [
-        "dist"
+        "dist",
+        "skills"
     ],
     "scripts": {
         "build": "rm -rf dist && tsc -p tsconfig.build.json",

package/dist/src/cli.js

@@ -4,6 +4,8 @@ import pkg from '../package.json' with { type: 'json' };
 import show from "./commands/show.js";
 import list from "./commands/list.js";
 import use from "./commands/use.js";
+import check from "./commands/check.js";
+import { install, uninstall } from "./commands/hook.js";
 import add from "./commands/add.js";
 import edit from "./commands/edit.js";
 import remove from "./commands/remove.js";
@@ -32,6 +34,22 @@ program
     .option('--json', 'Print the result as JSON, without prompting (a profile name is required)')
     .option('--update-origin', 'Update the origin remote to match the profile, without asking')
     .action(use);
+program
+    .command('check')
+    .description('Check that the git config of this repo matches its profile, failing if not. For use in a pre-commit hook.')
+    .option('--json', 'Print the result as JSON')
+    .action(check);
+const hook = program
+    .command('hook')
+    .description('Manage the pre-commit hook that runs `git who check` in this repo.');
+hook
+    .command('install')
+    .description('Run `git who check` before each commit in this repo.')
+    .action(() => install());
+hook
+    .command('uninstall')
+    .description('Stop running `git who check` before each commit in this repo.')
+    .action(() => uninstall());
 program
     .command('add')
     .description('Add a new profile.')

package/dist/src/commands/check.js

@@ -0,0 +1,41 @@
+import { simpleGit } from 'simple-git';
+import log from "../utils/log.js";
+import { loadProfiles } from "../utils/profiles.js";
+import { resolveFromGit } from "../utils/repo-profile.js";
+const NOT_SET = '(not set)';
+const quote = (value) => value === undefined ? NOT_SET : `'${value}'`;
+/**
+ * One line per setting that differs: what the profile expects and what git has. A profile without a signing key
+ * expects the signing settings to be unset.
+ */
+function describeMismatches(profile, mismatches) {
+    const settings = [
+        ['username', 'user.name', profile.username],
+        ['email', 'user.email', profile.email],
+        ['signingKey', 'user.signingKey', profile.signingKey],
+        ['signingMethod', 'commit signing', profile.signingMethod],
+    ];
+    return settings
+        .filter(([field]) => field in mismatches)
+        .map(([field, label, expected]) => `  ${label}: expected ${quote(expected)}, found ${quote(mismatches[field])}`);
+}
+/**
+ * Check that the current repo's git config matches its profile, for use in a pre-commit hook. A passing check prints
+ * nothing, so a hook adds no noise to a commit, unless `json` is set, which prints the profile that matched.
+ *
+ * @throws {Error} If the current directory is not a git repo, no profile can be resolved for it, or the git config
+ * differs from the profile. The message of the last names each setting that differs.
+ */
+export default async function check(options = {}) {
+    if (!await simpleGit().checkIsRepo()) {
+        throw new Error('The current directory must have a git repository to check a profile.');
+    }
+    const { profile, derived, mismatches } = await resolveFromGit(await loadProfiles());
+    if (mismatches && Object.keys(mismatches).length > 0) {
+        const lines = describeMismatches(profile, mismatches);
+        throw new Error([`Git config does not match profile '${profile.name}':`, ...lines].join('\n'));
+    }
+    if (options.json) {
+        log.json({ profile, derived });
+    }
+}

package/dist/src/commands/hook.js

@@ -0,0 +1,63 @@
+import { simpleGit } from 'simple-git';
+import log from "../utils/log.js";
+const EVENT = 'pre-commit';
+const HOOK_NAME = 'git-who';
+const COMMAND = 'git who check';
+const COMMAND_KEY = `hook.${HOOK_NAME}.command`;
+const EVENT_KEY = `hook.${HOOK_NAME}.event`;
+/**
+ * Whether git will run the hook for the event. A git that has no config hooks does not list it, and silently never
+ * runs it, so the install is only trusted once git says it sees the hook. `git hook list` also fails when nothing is
+ * listed, so a failure reads as not listed.
+ */
+async function isListed(git) {
+    try {
+        const output = await git.raw(['hook', 'list', EVENT]);
+        return output.split('\n').some((line) => line.trim() === HOOK_NAME);
+    }
+    catch {
+        return false;
+    }
+}
+async function removeConfig(git) {
+    await git.raw(['config', '--local', '--unset', COMMAND_KEY]);
+    await git.raw(['config', '--local', '--unset-all', EVENT_KEY]);
+}
+/**
+ * Make the current repo run `git who check` before each commit, using git's config hooks, so any `pre-commit` hook
+ * file the repo already has (such as husky's) keeps running too. Installing again is harmless.
+ *
+ * @throws {Error} If the current directory is not a git repo, or git does not list the hook once it is set, which
+ * means it is too old to run config hooks. The config is put back in that case.
+ */
+export async function install() {
+    const git = simpleGit();
+    if (!await git.checkIsRepo()) {
+        throw new Error('The current directory must have a git repository to install the hook.');
+    }
+    await git.addConfig(COMMAND_KEY, COMMAND, false, 'local');
+    await git.addConfig(EVENT_KEY, EVENT, false, 'local');
+    if (!await isListed(git)) {
+        await removeConfig(git);
+        throw new Error('Git did not list the hook once it was installed, so it may be too old to run config hooks (hook.<name>.*). The hook was not installed.');
+    }
+    log.info(`Installed the ${EVENT} hook. Commits in this repo now run \`${COMMAND}\`.`);
+}
+/**
+ * Take the hook that `install` set out of the current repo's config. A `pre-commit` hook file is never touched.
+ *
+ * @throws {Error} If the current directory is not a git repo.
+ */
+export async function uninstall() {
+    const git = simpleGit();
+    if (!await git.checkIsRepo()) {
+        throw new Error('The current directory must have a git repository to uninstall the hook.');
+    }
+    const { value } = await git.getConfig(COMMAND_KEY, 'local');
+    if (!value) {
+        log.info(`The ${EVENT} hook is not installed.`);
+        return;
+    }
+    await removeConfig(git);
+    log.info(`Removed the ${EVENT} hook.`);
+}

package/dist/src/commands/show.js

@@ -2,88 +2,10 @@ import { simpleGit } from 'simple-git';
 import { SIGNING_METHOD } from "../profile.js";
 import log from "../utils/log.js";
 import { printProfile } from "../utils/display.js";
-import { loadProfiles, getActiveProfileName } from "../utils/profiles.js";
+import { loadProfiles } from "../utils/profiles.js";
+import { resolveFromGit } from "../utils/repo-profile.js";
 import { listSshKeys } from "../utils/ssh.js";
 import { listGpgKeys } from "../utils/gpg.js";
-/**
- * Compare a profile with the repo's local git config. A field is only present in the result when the two differ, and
- * its value is what git has (`undefined` when git has nothing set).
- *
- * Git's signing method is only defined when `commit.gpgsign` is `true`: `gpg.format` of `openpgp` (or unset) is gpg,
- * `ssh` is ssh. Any other format, such as x509, is not supported and reads as git not signing.
- */
-function buildMismatches(actual, git) {
-    const mismatches = {};
-    if (actual.username !== git.username) {
-        mismatches.username = git.username;
-    }
-    if (actual.email !== git.email) {
-        mismatches.email = git.email;
-    }
-    if (actual.signingKey !== git.signingKey) {
-        mismatches.signingKey = git.signingKey;
-    }
-    let gitSigningMethod;
-    if (git.signCommits === 'true') {
-        if (!git.signingMethod || git.signingMethod === 'openpgp') {
-            gitSigningMethod = SIGNING_METHOD.GPG;
-        }
-        else if (git.signingMethod === 'ssh') {
-            gitSigningMethod = SIGNING_METHOD.SSH;
-        }
-    }
-    if (actual.signingMethod !== gitSigningMethod) {
-        mismatches.signingMethod = gitSigningMethod;
-    }
-    return mismatches;
-}
-async function readGitConfig() {
-    const git = simpleGit();
-    const [name, { value: username }, { value: email }, { value: signCommits }, { value: signingKey }, { value: signingMethod },] = await Promise.all([
-        getActiveProfileName(git),
-        git.getConfig('user.name', 'local'),
-        git.getConfig('user.email', 'local'),
-        git.getConfig('commit.gpgsign', 'local'),
-        git.getConfig('user.signingKey', 'local'),
-        git.getConfig('gpg.format', 'local'),
-    ]);
-    return {
-        name,
-        username: username ?? undefined,
-        email: email ?? undefined,
-        signCommits: signCommits ?? undefined,
-        signingKey: signingKey ?? undefined,
-        signingMethod: signingMethod ?? undefined,
-    };
-}
-/**
- * Find the profile for the current repo: the one named by `gitwho.profile`, otherwise the single profile whose
- * username and email match the git config (flagged as derived).
- *
- * @throws {Error} If `gitwho.profile` names a missing profile and nothing else matches uniquely, if several profiles
- * match with no active profile set, or if no profile is set and none match. A missing active profile takes priority
- * over multiple matches, since it is the underlying cause.
- */
-async function resolveFromGit(profiles) {
-    const gitData = await readGitConfig();
-    const profile = profiles.find((p) => p.name === gitData.name);
-    if (profile) {
-        const mismatches = buildMismatches(profile, gitData);
-        return { profile, derived: false, mismatches };
-    }
-    const matches = profiles.filter((p) => p.username === gitData.username && p.email === gitData.email);
-    if (matches.length === 1) {
-        const mismatches = buildMismatches(matches[0], gitData);
-        return { profile: matches[0], derived: true, mismatches };
-    }
-    else if (gitData.name) {
-        throw new Error(`Active profile '${gitData.name}' not found — it may have been deleted.`);
-    }
-    else if (matches.length > 1) {
-        throw new Error('Multiple profiles match the current git config — set one explicitly with `git who use <profile>`.');
-    }
-    throw new Error('No profile set and none found matching the current git config.');
-}
 async function buildStatus(resolved) {
     let signingKeyStatus;
     if (resolved.profile.signingMethod === SIGNING_METHOD.SSH) {

package/dist/src/utils/repo-profile.js

@@ -0,0 +1,82 @@
+import { simpleGit } from 'simple-git';
+import { SIGNING_METHOD } from "../profile.js";
+import { getActiveProfileName } from "./profiles.js";
+/**
+ * Compare a profile with the repo's local git config. A field is only present in the result when the two differ, and
+ * its value is what git has (`undefined` when git has nothing set).
+ *
+ * Git's signing method is only defined when `commit.gpgsign` is `true`: `gpg.format` of `openpgp` (or unset) is gpg,
+ * `ssh` is ssh. Any other format, such as x509, is not supported and reads as git not signing.
+ */
+function buildMismatches(actual, git) {
+    const mismatches = {};
+    if (actual.username !== git.username) {
+        mismatches.username = git.username;
+    }
+    if (actual.email !== git.email) {
+        mismatches.email = git.email;
+    }
+    if (actual.signingKey !== git.signingKey) {
+        mismatches.signingKey = git.signingKey;
+    }
+    let gitSigningMethod;
+    if (git.signCommits === 'true') {
+        if (!git.signingMethod || git.signingMethod === 'openpgp') {
+            gitSigningMethod = SIGNING_METHOD.GPG;
+        }
+        else if (git.signingMethod === 'ssh') {
+            gitSigningMethod = SIGNING_METHOD.SSH;
+        }
+    }
+    if (actual.signingMethod !== gitSigningMethod) {
+        mismatches.signingMethod = gitSigningMethod;
+    }
+    return mismatches;
+}
+async function readGitConfig() {
+    const git = simpleGit();
+    const [name, { value: username }, { value: email }, { value: signCommits }, { value: signingKey }, { value: signingMethod },] = await Promise.all([
+        getActiveProfileName(git),
+        git.getConfig('user.name', 'local'),
+        git.getConfig('user.email', 'local'),
+        git.getConfig('commit.gpgsign', 'local'),
+        git.getConfig('user.signingKey', 'local'),
+        git.getConfig('gpg.format', 'local'),
+    ]);
+    return {
+        name,
+        username: username ?? undefined,
+        email: email ?? undefined,
+        signCommits: signCommits ?? undefined,
+        signingKey: signingKey ?? undefined,
+        signingMethod: signingMethod ?? undefined,
+    };
+}
+/**
+ * Find the profile for the current repo: the one named by `gitwho.profile`, otherwise the single profile whose
+ * username and email match the git config (flagged as derived).
+ *
+ * @throws {Error} If `gitwho.profile` names a missing profile and nothing else matches uniquely, if several profiles
+ * match with no active profile set, or if no profile is set and none match. A missing active profile takes priority
+ * over multiple matches, since it is the underlying cause.
+ */
+export async function resolveFromGit(profiles) {
+    const gitData = await readGitConfig();
+    const profile = profiles.find((p) => p.name === gitData.name);
+    if (profile) {
+        const mismatches = buildMismatches(profile, gitData);
+        return { profile, derived: false, mismatches };
+    }
+    const matches = profiles.filter((p) => p.username === gitData.username && p.email === gitData.email);
+    if (matches.length === 1) {
+        const mismatches = buildMismatches(matches[0], gitData);
+        return { profile: matches[0], derived: true, mismatches };
+    }
+    else if (gitData.name) {
+        throw new Error(`Active profile '${gitData.name}' not found — it may have been deleted.`);
+    }
+    else if (matches.length > 1) {
+        throw new Error('Multiple profiles match the current git config — set one explicitly with `git who use <profile>`.');
+    }
+    throw new Error('No profile set and none found matching the current git config.');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bstopp/git-who",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "Manage git profiles for per-project SSH account configuration.",
   "license": "Apache-2.0",
@@ -19,7 +19,8 @@
     "access": "public"
   },
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.build.json",

package/skills/git-who/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: git-who
+description: Check or switch which git identity a repo uses (SSH host, user.name, user.email, commit signing) with the `git who` CLI. Use before committing or pushing in a repo that may belong to another account, when a commit went out under the wrong name or email, or when asked to use a named profile such as work or personal.
+---
+
+# git-who
+
+`git who` keeps named **profiles**. A profile is an SSH host alias, a `user.name`, a `user.email` and optionally a
+commit-signing key. Applying a profile to a repo writes those into the repo's local git config. Use it so that commits
+and pushes in a repo go out under the right account.
+
+Always pass `--json` and read stdout. Without it the commands print text meant for people, and some of them prompt.
+
+## Commands you may run
+
+| Command | Use it to |
+| --- | --- |
+| `git who list --json` | See which profiles exist and which one the current repo uses (`active`). |
+| `git who show --json` | Check the current repo against its profile. |
+| `git who show <name> --json` | Read one profile's details. |
+| `git who use <name> --json` | Apply a profile to the current repo. |
+| `git who check --json` | Pass or fail: does the current repo match its profile? Exits non-zero, with the differences in the error, if not. |
+
+Never run `git who add`, `edit` or `remove`. They are interactive and meant for the user. If a profile is missing or
+wrong, tell the user and let them run those. Do not run `git who hook install` or `hook uninstall` either: they change
+what every commit in the repo does, so that is the user's decision.
+
+## Checking a repo
+
+Run `git who show --json` in the repo.
+
+```json
+{
+  "profile": { "name": "work", "host": "github-work", "username": "Bryan Work", "email": "bryan@work.com" },
+  "derived": false,
+  "signingKeyStatus": { "found": true },
+  "mismatches": { "email": "bryan@personal.com" }
+}
+```
+
+- `profile` is the profile the repo is set to use.
+- `derived: true` means no profile is set on the repo, and this one was only matched by name and email. Apply it with
+  `use` if it is the right one.
+- `mismatches` lists the fields where the repo's git config differs from the profile, with the value git currently has.
+  `null` means git has nothing set. `{}` means the repo is correct. If there are mismatches, the repo has drifted, and
+  `use` fixes it.
+- `signingKeyStatus.found: false` means the profile's signing key is not on this machine. Commits will not be signed as
+  the profile expects. Tell the user, because you cannot fix that.
+- `signingMethod` and `signingKey` are missing from `profile` when the profile does not sign.
+
+## Switching a repo
+
+1. Run `git who list --json` and pick the profile whose `name` matches what the user asked for. If you are unsure which
+   one is meant, ask the user instead of guessing.
+2. Run `git who use <name> --json`.
+
+```json
+{ "profile": { "name": "work", "...": "..." }, "originUpdated": false, "origin": { "current": "git@github-personal:org/repo.git", "expected": "git@github-work:org/repo.git" } }
+```
+
+`origin` is only present when the repo's `origin` remote does not use the profile's host. Pushes would go out under
+the other account. `use` leaves `origin` alone by default (`originUpdated: false`).
+
+- Do **not** add `--update-origin` on your own. It rewrites the remote. Say what `current` and `expected` are, and add
+  the flag only if the user agrees or already asked for it.
+- If the repo is correct afterwards, `git who show --json` shows `mismatches: {}`.
+
+## Errors
+
+A failure prints `{ "error": "...", "causes": ["..."] }` on stdout and exits with code 1. `causes` lists the wrapped
+errors, outermost first.
+
+| Error | What to do |
+| --- | --- |
+| `A profile name is required with --json.` | Pass a profile name to `use`. |
+| `Profile <name> not found.` | Run `list` and use one of its names. If none fits, ask the user. |
+| `The current directory must have a git repository to use a profile.` | Run it from inside the repo. |
+| `No profiles found. ...` | Nothing is set up. The user has to run `git who add`. |
+| `... key '...' not found for profile '...'` | The profile's signing key is missing. Tell the user. Do not work around it. |
+| `Git config does not match profile '<name>': ...` | From `check`, or from a commit stopped by the user's pre-commit hook. If `<name>` is clearly the right profile, run `git who use <name> --json` and retry the commit. If not, ask the user. |
+| `Failed to apply profile ...` | The git config may be partly updated. Run `git who show --json` to see what is left, then retry `use`. |
+
+## Rules
+
+- Check with `show` before you commit or push in a repo where the identity matters, and fix it with `use` if it has
+  drifted.
+- Do not edit `user.name`, `user.email` or the signing settings with `git config` to get around a `git who` error.
+  Report the error instead.
+- Do not use `git commit --no-verify` to get past a stopped commit. The hook is there to catch the wrong identity, so
+  fix the identity or ask the user.
+- Do not edit `~/.git-who.cfg.json` or the `gitwho.profile` setting by hand.