A wrong Git identity is easy to ignore until it shows up on every commit, pull request, and code review. To set Git username and email values cleanly, configure 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 repository-local config beats global config. These values are commit metadata, not GitHub login credentials or passwords. That is why a work repository can use a company address while everything else still uses your personal one. A clean setup uses exact git config commands, keeps track of the files they write to, and verifies what Git will stamp on the next commit.
Configure Git Username and Email with git config
Set the default identity with git config --global user.name and git config --global user.email. For the common global setup, run:
git config --global user.name "Jane Developer"
git config --global user.email "jane@example.com"Inside a repository, omit --global or add --local when only that repository should use a different name or email.
The command names matter: Git stores the display name in user.name and the commit email in user.email. These values are not your GitHub, GitLab, or Bitbucket password, and user.name does not have to match a hosting-service username.
Choose the Git Name and Email Values
Use a name that teammates will recognize in commit history. For the email, use an address your Git hosting service recognizes if you want commits attributed to your account; if you use a privacy or noreply address, copy that exact address from the hosting service account settings.
Understand Git Config Scope
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 |
For most readers, the decision is simple: set a global identity first, add a local identity only when one repository needs different commit metadata, and use conditional includes only when whole folders of repositories should share another identity.
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.
The official Pro Git First-Time Git Setup section covers the same identity settings, config-file precedence, and project-specific override behavior.
Git Username and Email Command Quick Reference
| Task | Compatible Command | What It Does |
|---|---|---|
| Check the current effective Git username | git config user.name | Shows the username Git will use in the current repository. |
| Check the current effective Git email | git config user.email | Shows the email Git will use in the current repository. |
| Set a global Git username | git config --global user.name "Jane Developer" | Stores your default username for all repositories. |
| Set a global Git email | git config --global user.email "jane@example.com" | Stores your default commit email for all repositories. |
| Set a local Git username | git config --local user.name "Jane Work" | Overrides the username only in the current repository. |
| Set a local Git email | git config --local user.email "jane@company.test" | Overrides the email only in the current repository. |
| Show which file supplied the current value | git config --show-origin user.name | Prints the active value and the config file it came from. |
| List Git username and email settings from every scope | git config --show-origin --get-regexp '^user\.(name|email)$' | Shows every matching username and email entry Git can see. |
These flag-style commands work on current Git releases and older distro-packaged versions. The upstream manual also documents subcommands such as git config get, git config set, git config list, and git config unset, so either form is valid when the installed Git version supports it. When a newer example uses git config set --global user.name "Jane Developer", treat it as the same operation as git config --global user.name "Jane Developer".
Some supported Linux distributions ship Git versions that predate the newer subcommands. If Git reports that
get,set, orunsetis unknown, use the compatible flag-style forms instead.For checks, use
git config --global user.namefor a global value orgit config user.namefor the effective value in the current repository. For removals, usegit config --global --unset user.nameorgit config --local --unset user.name, then repeat the same pattern foruser.email.
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
For 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, install Git on Rocky Linux, or install Git on CentOS Stream.
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. Direct value checks are cleaner than a full config list because they print only the values you care about.
git config --global user.name
git config --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 commands again later with different values if you need to change them.
git config --global user.name "Jane Developer"
git config --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
To confirm both the value and the file Git read it from, add --show-origin while checking the global value.
git config --global --show-origin user.name
git config --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 git config --local inside the repository to store the override in .git/config. Omitting --global also writes to the local repository by default, but --local makes the target explicit.
git config --local user.name "Jane Work"
git config --local 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 --show-origin --get-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 user.name
git config 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.
Verify Git Username and Email Sources
After global and local values are set, source checks help when Git still appears to read the wrong identity. Use these commands to see the active commit metadata and the files Git is reading.
Preview the Git Username and Email on the Next Commit
To see the identity Git would use right now, ask Git for the author identity directly. This is a useful final check before the first commit in a newly cloned repository.
git var GIT_AUTHOR_IDENTOutput resembles this format:
Jane 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-originRelevant output includes the config files that supply identity values:
file:/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.name=Jane Work file:.git/config user.email=jane@company.test
The git-config documentation lists git config list as the subcommand equivalent. For broad Linux compatibility, git config --list --show-origin remains the safer copy-paste form.
Manage Git Username and Email Overrides
Once the main identity works, keep maintenance commands separate from setup. Conditional includes handle repeated work and personal splits, unset commands remove stale overrides, and user.useConfigOnly makes missing identity values fail loudly.
Know What Git Username and Email Changes Affect
Changing Git username and email values only affects new commits. Existing commits keep the author and committer information they already recorded unless you intentionally rewrite history.
History rewriting changes commit hashes and can disrupt shared branches. Do not rewrite commits that other people may already have pulled unless your team has agreed on the recovery plan.
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 --show-origin --get-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
The git-config documentation defines includeIf as a conditional way to load another config file. 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 --local --unset user.name
git config --local --unset user.email
git config user.name
git config 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
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 --global --unset user.name
git config --global --unset user.emailThen verify that the global values are gone:
git config --global user.name
git config --global user.emailBoth commands should return directly to the prompt with no output.
Force Git to Require an Explicit Username and Email
By default, Git can sometimes guess parts of an identity from the environment. To make Git fail loudly instead, enable user.useConfigOnly.
git config --global user.useConfigOnly true
git config --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. To let Git resume guessing later, remove the setting with
git config --global --unset user.useConfigOnly.
Troubleshoot Common Git Username and Email Errors
Use the exact error text to choose the matching fix. Most Git identity problems come from running a local command outside a repository, missing identity values, a forgotten local override, or a malformed config file.
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, set the local identity from that directory and retest the effective values.
git config --local user.name "Jane Work"
git config --local user.email "jane@company.test"
git config user.name
git config user.emailJane Work jane@company.test
If the directory is not a repository yet, run git init only when you intend to make that directory a Git repository. Otherwise, use the global commands until the project has a repository.
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 print the flag-style commands in this error message because they work across old and new Git versions. On newer Git releases, git config set --global ... is the equivalent subcommand form.
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 --global user.name "Jane Developer"
git config --global user.email "jane@example.com"
git config user.name
git config user.emailJane Developer jane@example.com
Git Keeps Using the Wrong Email in One Repository
Check every matching Git identity value and the file that supplied it:
git config --show-origin --get-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
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 --local --unset user.name
git config --local --unset user.email
git config user.name
git config 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.
Back up the file, open it, remove or repair the malformed line, and save the corrected config:
cp ~/.gitconfig ~/.gitconfig.bak.$(date +%Y%m%d-%H%M%S)
nano ~/.gitconfigAfter saving the file, list the global config again. Git should print the repaired file instead of another bad-line error.
git config --global --list --show-originfile:/home/josh/.gitconfig user.name=Jane Developer file:/home/josh/.gitconfig user.email=jane@example.com
Once Git can read the file again, compare it with the timestamped ~/.gitconfig.bak.* backup only if you need to recover other settings. For username and email changes, using git config is safer than editing the file by hand.
Finish Git Username and Email Setup
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 in published comments:
<code>command</code>command<strong>bold</strong><em>italic</em><blockquote>quote</blockquote>