A wrong Git identity is easy to ignore until it shows up on every commit, pull request, and code review. To configure a Git username and email address cleanly, set a global identity for everyday work, override it only in repositories that need something different, and verify which config file Git is actually reading.
Git does not keep one magic identity. It reads configuration in layers, and the repository-local config beats the global one. That is why a work repository can use a company address while everything else still uses your personal one. The sections below show the exact git config commands, the files they write to, and the fastest ways to see what Git will stamp on the next commit.
Understand Git Username and Email Configuration
Git can read configuration from three scopes: system, global, and local. Most people only need the global and local scopes for username and email. Global settings apply to every repository for your user account, while local settings only apply inside the current repository and override the global values there.
| Git Config Scope | Typical File | Best Use | Priority |
|---|---|---|---|
| System | /etc/gitconfig | Admin-managed defaults for all users on a machine | Lowest |
| Global | ~/.gitconfig | Your default personal or work identity across repositories | Medium |
| Local | .git/config | A repository-specific identity that should override your usual one | Highest |
If Git keeps using the wrong email in one repository, a local override in
.git/configis usually the reason. The official git-config manual page documents the same config scopes and theuser.name,user.email, anduser.useConfigOnlysettings used in this guide.
If you want the longer explanation behind those scopes, the official Pro Git chapter on Git Configuration is the best follow-up reference.
Git Username and Email Command Quick Reference
| Task | Command | What It Does |
|---|---|---|
| Check the current effective Git username | git config get user.name | Shows the username Git will use in the current repository context. |
| Check the current effective Git email | git config get user.email | Shows the email Git will use in the current repository context. |
| Set a global Git username | git config set --global user.name "Jane Developer" | Stores your default username for all repositories. |
| Set a global Git email | git config set --global user.email "jane@example.com" | Stores your default commit email for all repositories. |
| Set a local Git username | git config set user.name "Jane Work" | Overrides the username only in the current repository. |
| Set a local Git email | git config set user.email "jane@company.test" | Overrides the email only in the current repository. |
| Show which file supplied the current value | git config get --show-origin user.name | Prints both the active value and the config file it came from. |
| List matching Git username and email settings from every scope | git config get --show-origin --all --show-names --regexp '^user\.(name|email)$' | Shows every matching username and email entry Git can see. |
| List all Git config values with their source files | git config list --show-origin | Dumps every visible Git setting, not just identity values. |
| Require an explicitly configured Git identity | git config set --global user.useConfigOnly true | Stops Git from guessing a fallback name or email. |
The current git-config documentation uses subcommands such as get, set, list, and unset. Older tutorials often show --get, --list, or --unset; those still work, but this guide sticks to the newer form.
Install Git If the Git Command Is Missing
Git is already installed on many desktops and developer-focused distributions, but minimal servers, containers, and fresh setups can still return git: command not found. If that happens, install Git with your distro package manager and then rerun the version check.
# Debian and Ubuntu
sudo apt update && sudo apt install git
# Fedora, RHEL, Rocky Linux, and AlmaLinux
sudo dnf install git
# Arch Linux
sudo pacman -S git
# openSUSE
sudo zypper install gitVerify that Git is available:
git --versiongit version 2.x.x
If you want distro-specific installation steps, use the guides to install or upgrade Git on Ubuntu, install Git on Debian, install Git on Fedora, install Git on Linux Mint, install Git on Arch Linux, or install Git on Rocky Linux.
Set a Global Git Username and Email
Your global Git username and email become the default identity for every repository that does not define its own local override. This is the right place to set the identity you use most often.
Check the Current Global Git Username and Email
Before changing anything, check whether a global identity already exists. Using git config get is cleaner than git config list because it prints only the value you care about.
git config get --global user.name
git config get --global user.emailJane Developer jane@example.com
If both commands print nothing, the global Git username and email are not set yet. That is normal on a fresh install.
Set the Global Git Username and Email
Set your default identity with the --global scope. Run the same git config set commands again later with different values if you need to change them.
git config set --global user.name "Jane Developer"
git config set --global user.email "jane@example.com"On most Linux setups, Git writes these values to ~/.gitconfig. Some XDG-aware setups also read ~/.config/git/config, but ~/.gitconfig is still the path most users will see.
Show Which Git Config File Sets the Global Username and Email
If you want to confirm both the value and the file Git read it from, add --show-origin.
git config get --global --show-origin user.name
git config get --global --show-origin user.emailfile:/home/josh/.gitconfig Jane Developer file:/home/josh/.gitconfig jane@example.com
The path will reflect your actual home directory. If Git reports ~/.gitconfig or your home path here, the global identity is set where it should be.
Set a Local Git Username and Email for One Repository
Use a local Git username and email when one repository needs a different identity from your default. That is common when you contribute to both personal and work projects from the same machine.
Move Into the Git Repository First
Local config only works inside a Git repository, so start in the project root.
cd ~/projects/client-portalSet a Local Git Username and Email
Run the same git config set command without --global to store the override in the current repository.
git config set user.name "Jane Work"
git config set user.email "jane@company.test"Git writes these values to .git/config in the repository, not to your global config file.
Show Which Git Config File Overrides the Global Values
If both global and local values exist, Git keeps both, but the local ones win inside this repository. The easiest way to see that is to list every matching setting with its source file.
git config get --show-origin --all --show-names --regexp '^user\.(name|email)$'file:/home/josh/.gitconfig user.name Jane Developer file:/home/josh/.gitconfig user.email jane@example.com file:.git/config user.name Jane Work file:.git/config user.email jane@company.test
That output shows both sets of values. Because the repository has its own .git/config entries, Git uses Jane Work and jane@company.test for new commits in this repository.
Check the Effective Git Username and Email in This Repository
After setting the local override, confirm the effective values Git will use here.
git config get user.name
git config get user.emailJane Work jane@company.test
Those are the values Git will use for commits in the current repository unless you change the local config again.
Use Advanced Git Username and Email Checks
Most setups stop at global and local values, but a couple of extra checks make Git identity problems much easier to spot and prevent.
Preview the Git Username and Email on the Next Commit
If you want to see the identity Git would use right now, ask Git for the author identity directly. This is a handy sanity check before the first commit in a newly cloned repository.
git var GIT_AUTHOR_IDENTJane Work <jane@company.test> 1772238821 +0000
The name and email are the part that matters here. The trailing number is the current Unix timestamp, followed by your timezone offset.
List All Git Config Values and Their Source Files
If the focused identity checks still leave you wondering what Git is reading, list the full config view. This is noisier than the identity-only commands, but it helps when another include file, system default, or repository setting is affecting more than just user.name and user.email.
git config list --show-originfile:/etc/gitconfig init.defaultBranch=main file:/home/josh/.gitconfig user.name=Jane Developer file:/home/josh/.gitconfig user.email=jane@example.com file:.git/config user.email=jane@company.test
The current git-config documentation uses git config list as the canonical form. If you only care about identity, the earlier get and get --regexp checks are still easier to read.
Automatically Switch Git Username and Email by Repository Location
If you keep work repositories under one path and personal repositories somewhere else, Git can switch identities automatically with a conditional include. This saves you from setting the same local override in every new repository.
Add the include rule to your main Git config file:
[user]
name = Jane Personal
email = jane@example.com
[includeIf "gitdir:~/Work/"]
path = ~/.gitconfig-workThen create the work-specific file it points to:
[user]
name = Jane Work
email = jane@company.testIn a repository under ~/Work/, verify that Git sees both files and prefers the work identity:
git config get --show-origin --all --show-names --regexp '^user\.(name|email)$'file:/home/josh/.gitconfig user.name Jane Personal file:/home/josh/.gitconfig user.email jane@example.com file:/home/josh/.gitconfig-work user.name Jane Work file:/home/josh/.gitconfig-work user.email jane@company.test
According to the git-config documentation, includeIf can load another config file when its condition matches. The gitdir:~/Work/ pattern applies that extra file to repositories inside ~/Work/.
Remove a Local Git Username and Email and Fall Back to Global
If a repository-specific override is no longer needed, unset the local values. Git then falls back to the global identity automatically.
git config unset --local user.name
git config unset --local user.email
git config get user.name
git config get user.emailJane Developer jane@example.com
This is the quickest fix when one repository keeps using an old work or client email after you thought you changed your global Git config.
Remove a Global Git Username and Email
If you want to clear the default identity completely, unset the global values. Git will stop using them until you set new ones or a repository provides its own local identity.
git config unset --global user.name
git config unset --global user.emailThen verify that the global values are gone:
git config get --global user.name
git config get --global user.email(no output)
Force Git to Require an Explicit Username and Email
By default, Git can sometimes guess parts of an identity from the environment. If you want Git to stop guessing and fail loudly instead, enable user.useConfigOnly.
git config set --global user.useConfigOnly true
git config get --global user.useConfigOnlytrue
This setting is useful on shared machines, new workstations, and CI environments where a guessed email is worse than a hard failure. If you want Git to resume guessing later, remove the setting with
git config unset --global user.useConfigOnly.
Troubleshoot Common Git Username and Email Errors
Git Says Local Config Can Only Be Used Inside a Repository
fatal: --local can only be used inside a git repository
This happens when you run a local Git config command outside a repository. Move into the project first, then verify Git sees the repository root.
cd ~/projects/client-portal
git rev-parse --show-toplevel/home/josh/projects/client-portal
If Git prints the repository path, rerun the local git config command from there.
Git Refuses to Commit Because the Author Identity Is Unknown
Author identity unknown *** Please tell me who you are. Run git config --global user.email "you@example.com" git config --global user.name "Your Name" to set your account's default identity. Omit --global to set the identity only in this repository. fatal: no email was given and auto-detection is disabled
Git may still print the older flag-style commands in this error message. The current equivalent is git config set --global ... or git config set ... for a repository-only fix.
This usually appears when no Git username and email are configured and user.useConfigOnly is enabled. Set the missing identity values, then verify them before retrying the commit.
git config set --global user.name "Jane Developer"
git config set --global user.email "jane@example.com"
git config get user.name
git config get user.emailJane Developer jane@example.com
Git Keeps Using the Wrong Email in One Repository
file:/home/josh/.gitconfig user.name Jane Developer file:/home/josh/.gitconfig user.email jane@example.com file:.git/config user.name Jane Work file:.git/config user.email jane@company.test
This is the usual sign that a local override is still set in the repository. Remove the local values if you want the repository to inherit your global identity again.
git config unset --local user.name
git config unset --local user.email
git config get user.name
git config get user.emailJane Developer jane@example.com
Git Reports a Bad Config Line After Manual Edits
fatal: bad config line 2 in file /home/josh/.gitconfig
This means the config file was edited manually and the syntax is broken. Git will not read or update that file until the malformed line is removed.
mv ~/.gitconfig ~/.gitconfig.bak
git config set --global user.name "Jane Developer"
git config set --global user.email "jane@example.com"[user] name = Jane Developer email = jane@example.com
Once the new file is written, compare it with ~/.gitconfig.bak only if you need to recover other settings. For username and email changes, using git config is safer than editing the file by hand.
Frequently Asked Questions About Git Username and Email
Run git config get user.name and git config get user.email to see the effective values Git will use in the current repository context. If you also want the source file, use git config get --show-origin user.name and git config get --show-origin user.email.
git config --global and git config --local?
The --global scope writes your default identity to your user-level config, usually ~/.gitconfig. In the current git-config docs you will most often see that as git config set --global. The --local scope writes only to the current repository’s .git/config file, and those local values override the global ones in that repository.
Yes. Git supports conditional includes through includeIf, which lets you load another config file when a repository path matches a rule such as gitdir:~/Work/. This is useful when you want one identity for work repositories and another for personal repositories.
Global values are usually stored in ~/.gitconfig, while repository-specific values are stored in .git/config. Git can also read system-wide defaults from /etc/gitconfig on Linux.
No. Changing Git username and email only affects new commits made after the change. Existing commits keep the author and committer information they already recorded unless you rewrite history.
A repository-specific value in .git/config is usually overriding the global value from ~/.gitconfig. Run git config get --show-origin --all --show-names --regexp '^user\.(name|email)$' to see every matching entry and which file supplied it.
Git Username and Email Conclusion
Once Git is pulling the right identity from the right file, the problem stops being mysterious. A global default covers everyday work, local overrides stay boxed into the repositories that need them, and a quick check shows what the next commit will use. If you are cleaning up Git history next, see undo the last Git commit or rename a local and remote Git branch.
Formatting tips for your comment
You can use basic HTML to format your comment. Useful tags currently allowed:
<code>command</code>command<strong>bold</strong><em>italic</em><blockquote>quote</blockquote>