Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Configuration Options

The user.* settings

Reference for Git's user.* settings: name, email, signingKey and useConfigOnly. Learn how author identity is chosen and how to avoid commits with a wrong email.

The user.* settings tell Git who you are. Every commit records an author and a committer, each with a name, an email address and a date. user.name and user.email supply the first two. Without them Git tries to guess from the system account and host name, which usually produces an address you did not intend to publish.

Two more settings live in the same group: user.signingKey selects the key used for signing commits and tags, and user.useConfigOnly turns the guessing off so that a missing identity is an error instead of a silent mistake.

Terminal
git config --global user.name "Ada Lovelace"
git config --global user.email "[email protected]"
git config user.signingKey 3AA5C34371567BD2    # key id, or a path to an SSH public key
git config --global user.useConfigOnly true

Try it

Bash Identity from config

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Bash Refusing to guess

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Syntax

Terminal
git config [--global | --local] user.name  <name>
git config [--global | --local] user.email <address>
git config [--global | --local] user.signingKey <key>
git config [--global | --local] user.useConfigOnly <bool>
Name Description
user.name Name stored in the author and committer lines. Any text, no angle brackets.
user.email Email stored beside the name. Git does not validate it.
user.signingKey GPG key id, or for SSH signing (gpg.format=ssh) a public key path or literal key. Used by -S, commit.gpgSign and git tag -s.
user.useConfigOnly When true, Git never builds a name or email from the system account; a missing value stops the command.
author.name, author.email, committer.name, committer.email Set the two roles separately. They override user.*.

Errors: with an unusable identity Git prints "Author identity unknown" followed by instructions, or with useConfigOnly "fatal: no email was given and auto-detection is disabled", and no commit is made.

Usage notes

  • Resolution order for the author: GIT_AUTHOR_NAME and GIT_AUTHOR_EMAIL, then author.*, then user.*, then the EMAIL environment variable (email only), then system guesses. The committer follows the same chain with GIT_COMMITTER_* and committer.*.
  • Per-project identities are best done with includeIf "gitdir:~/work/" in your global config, which pulls in a file that sets a work email only for repositories under that folder.
  • user.useConfigOnly pairs well with per-repository emails. Leave user.email unset globally; the first commit in a new clone then fails and reminds you to choose which address belongs there.
  • Changing the setting does not rewrite history. Old commits keep the identity they were made with; to fix them use git commit --amend --reset-author or git rebase with --exec.
  • Matching signatures: a signed commit is verified against the committer email, so an email that is not on the key's identity shows "Good signature" with a warning on some hosts.
  • Hosting services link commits to accounts by email address. A typo means contributions that appear unlinked.
  • Inspect the value that applies with git var GIT_AUTHOR_IDENT, which also shows the date.