README.md

Git good

Git good makes sure your commits are saved under the right name and email.

Git stamps every commit with a name and email from its config. It doesn't care which account you're signed in with on GitHub, GitLab or Git Cafe. When nothing is set, Git guesses from your computer, and coding agents often fill the gap with a wrong or outdated address. Git good saves the identity you want once, stops Git from guessing, and tells you when a repo would commit under anything else.

Install

You need Git, and Node.js 20 or newer or Bun.

sh
1npm install -g git-good-cli
2# or
3bun add -g git-good-cli

The package is named git-good-cli, and the command it installs is git-good. Installed with Bun, it runs with Node when Node is on your PATH and with Bun otherwise.

Prefer a single file with no Node? bun run build in a clone of this repo creates dist/git-good (dist\git-good.exe on Windows). Copy it to any folder on your PATH.

Because the command starts with git-, Git also runs it as git good.

Use

Run git good on its own to open the start screen: pick setup, check or fix with the arrow keys and Enter, or press q to quit. Each command also runs directly, as below.

In a terminal, Git good uses color and asks questions with menus. When its output goes to a file, a pipe or another program, or when NO_COLOR or --json is set, it prints plain text and never asks anything. Exit codes are the same either way.

git good setup

Asks for your name and email and saves them as your profile. The profile lives in your config folder, not in any repo:

  • Windows: %APPDATA%\git-good\profile.json
  • macOS: ~/Library/Application Support/git-good/profile.json
  • Linux: ~/.config/git-good/profile.json

It also sets user.useConfigOnly = true in your global Git config, so Git refuses to commit instead of guessing. It sets your global user.name and user.email only if you say yes. You see every change before anything is written.

You can also save a different email for each host, such as a noreply address for git.cafe and another for github.com. Git picks it by the repo's remote URL, through an includeIf "hasconfig:remote.*.url:..." entry in your global config that points to a small file in git-good/hosts/. Every Git process uses it, including coding agents, in any repo or worktree on that host, with no per-repo setup. A repo without a remote, or on another host, uses your global user.email if you set one. This needs Git 2.36 or newer.

Outside a terminal it doesn't ask. Pass the answers as flags, and add --yes to apply the changes: git good setup --name "Your Name" --email you@example.com --no-global --yes. Add --host git.cafe=you@users.noreply.git.cafe once per host. Passing --host replaces the saved host emails; leaving it out keeps them.

check and fix compare against the email saved for the repo's host, and use your main email everywhere else.

git good check

Run it inside a repo. It asks Git which name and email the next commit will use, for both the author and the committer. That covers the repo's own config, your global config, git -c flags and the GIT_AUTHOR_* / GIT_COMMITTER_* environment variables. Then it compares the result with your profile.

When something is wrong, it says where the wrong value came from and how to fix it:

1 BAD my-app git.cafe
2
3 ✓ author screen <screen@users.noreply.git.cafe>
4 ✗ committer agent@example.com
5 should be screen@users.noreply.git.cafe
6 from the environment variable GIT_COMMITTER_EMAIL
7
8 → Remove the environment variable GIT_COMMITTER_EMAIL. A shell profile, terminal or agent app set it.

When git good fix would solve the problem, the check ends by asking whether to fix it now.

Exit codes: 0 match, 1 mismatch, 2 no identity, 3 no profile saved, 4 error.

Add --json to get the same result as JSON, for scripts, agent launchers and other apps. Add --quiet to print nothing when everything matches.

git good fix

Writes your profile into the current repo's own config (user.name and user.email), shows the before and after, and changes nothing else. If something still overrides it, such as an environment variable, it tells you what.

git good hook install

Adds a pre-commit hook to the current repo, so a commit under the wrong identity stops before it's made. It never replaces an existing hook. If one exists, it shows the line to add yourself.

The hook is a plain sh script. Git for Windows ships its own sh and runs hooks with it, so you don't need Bash installed.

Help

Run git good help or git-good --help. (git good --help makes Git look for a manual page instead.)

Develop

sh
1bun install
2bun test
3bun run typecheck
4bun src/cli.ts check

Set GIT_GOOD_CONFIG_DIR to keep test runs away from your real profile.

To publish to npm, bump version in package.json and run npm publish. It runs the type check and tests first, then builds dist/cli.js for Node.

License

MIT