Introduction

The Git "please tell me who you are" error appears when Git cannot determine the author identity for a commit. Git needs a user.name and user.email so it can write author metadata into the commit object. The fix is usually simple, but it is worth understanding the difference between local and global configuration so you do not solve the problem in the wrong scope.

Why Git Refuses the Commit

Each commit records author and committer information. If Git cannot resolve those values from configuration or environment variables, it stops and asks you to configure them.

A typical fix is:

git config --global user.name "Mark Qian"
git config --global user.email "[email protected]"

After that, new commits on the machine will use that identity unless a repository overrides it locally.

Choose Local or Global Scope Deliberately

Git supports multiple configuration scopes. The two most relevant are:

1. global, for your user account on the machine
2. local, for one repository only

Use global settings if the same identity should apply everywhere:

git config --global user.name "Mark Qian"
git config --global user.email "[email protected]"

Use local settings when one repository must use a different identity:

git config user.name "Work Account"
git config user.email "[email protected]"

This is common when you separate personal and company repositories.

Verify What Git Is Actually Reading

Do not guess which config value is winning. Ask Git directly:

git config --list --show-origin
git config user.name
git config user.email

The --show-origin flag is especially helpful because it tells you whether a value came from the system config, global config, or repository config file.

Common Causes Beyond Missing Config

Sometimes the identity is set, but Git still behaves unexpectedly. Typical reasons include:

• running inside a fresh container or CI job with no global config
• committing as a different OS user than expected
• relying on environment variables that are unset
• using a new machine without migrating Git config

In CI, it is common to set identity explicitly before creating automated commits:

git config user.name "ci-bot"
git config user.email "[email protected]"
git commit -m "Update generated files"

That makes the pipeline self-contained and predictable.

Understand That Commit Identity Is Metadata, Not Authentication

user.name and user.email tell Git what to write into the commit. They do not prove that you are authenticated to a remote. Pushing to GitHub or another remote is controlled separately through SSH keys, HTTPS credentials, or tokens.

That distinction matters because users often fix the identity error and then expect push authentication problems to disappear. They are different layers.

Fix Existing Wrong Identity if Needed

Setting config only affects future commits. If you already created local commits with the wrong author info, you need to rewrite those commits before pushing.

For the most recent commit:

git commit --amend --reset-author

For multiple local commits, interactive rebase may be appropriate, but only before those commits are shared.

Common Pitfalls

• Setting the identity globally when only one repository needed a different author.
• Forgetting that CI and containers usually need explicit Git config.
• Assuming user.email controls remote authentication to Git hosting providers.
• Fixing the config and expecting previously created commits to update automatically.
• Not checking git config --list --show-origin when conflicting config files exist.

Summary

• Git needs user.name and user.email to create commits.
• Set them globally for one-machine defaults or locally for repository-specific identities.
• Use git config --list --show-origin to see which config file is active.
• Commit identity and remote authentication are separate concerns.
• If old local commits have the wrong author, update them explicitly before pushing.