How To Configure user.name and user.email in Git (Step-by-Step Guide)
Configuring user.name and user.email is one of the first things Git expects you to do. These two settings control how your identity appears in Git commit history. If they’re missing or wrong, your commits can look anonymous, misattributed, or disconnected from your real profile on platforms like GitHub, GitLab, or Bitbucket.
This guide explains what these settings do, how to configure them properly, and the different ways you can scope them depending on how and where you use Git.
What user.name and user.email in Git Actually Do
Every time you run git commit, Git stores metadata along with your changes:
- Who made the commit
- When the commit was made
- A message describing the change
The “who” part is taken from:
- user.name → your display name in the commit
- user.email → your email in the commit
These values are stored inside each commit. Once a commit is created, its author name and email are baked in; changing your config later doesn’t rewrite old commits automatically.
Some key points:
- These values don’t affect your system account; they’re only for Git.
- Git hosting services (like GitHub) often use your email to link commits to your online profile.
- You can have different names/emails for different repositories if you want (e.g., work vs personal).
Think of user.name and user.email as your business card for that Git repository. Every commit you make carries a copy of that card.
Where Git Stores Your Name and Email: Global vs Local vs System
Git can store configuration in several “layers.” The same setting may be set in more than one place, and Git uses a priority order to decide which one wins.
Main config scopes in Git
| Scope | Command option | Typical file location | What it affects |
|---|---|---|---|
| System | --system | e.g. /etc/gitconfig | All users on the machine |
| Global | --global | e.g. ~/.gitconfig or ~/.config/git/config | All repos for your user account |
| Local | --local (default) | .git/config inside the repository | Only that specific Git repository |
Precedence: Local > Global > System
If a setting is defined locally, it overrides the global and system values.
For user.name and user.email:
- Most people set them globally once.
- Some people override them locally for specific repositories (e.g., work vs personal projects).
- System-level settings are less common and usually done by admins on shared machines.
How To Check Your Current Git user.name and user.email
Before changing anything, you can see what Git currently has configured.
To see what applies in the current repository (including inheritance):