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

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):

git config user.name git config user.email 

If nothing is returned, Git doesn’t have those values set at that scope.

To see all levels with their sources:

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

This shows which file (system, global, or local) defines each value.

To list your global config (for your user account):

git config --global --list 

Look for lines like:

user.name=Your Name [email protected] 

If they’re missing, Git will warn you when you try to commit.

How To Set Git user.name and user.email Globally

Global configuration is the most common, simplest setup: you define your identity once for your user account, and it applies to all repositories unless overridden.

From any terminal:

git config --global user.name "Your Real Name" git config --global user.email "[email protected]" 

After setting them, verify:

git config --global --get user.name git config --global --get user.email 

Typical things people put here:

• A readable, human name:
  "Alex Chen", "Maria Lopez", "Jane Doe"

• A primary email for development work:

  • For GitHub, many use the email associated with their GitHub account.
  • For privacy, some platforms offer noreply emails (e.g., [email protected]) that still link commits to your profile.

These global settings will be used for all new commits in any repository where you haven’t set a different local value.

How To Set user.name and user.email for a Single Repository

Sometimes you don’t want the same identity everywhere:

• You contribute to open source projects with a personal email.
• You work on company repositories with your work email.
• You maintain a public profile under a different name than your legal one.

In those cases, you can override the global settings locally in a specific repository.

1. Go to the repo directory:

   cd path/to/that/repository 

2. Set name and email for this repo only:

   git config user.name "Your Work Name" git config user.email "[email protected]" 

3. Confirm:

   git config --get user.name git config --get user.email 

These values will be saved in .git/config inside that repository and will take precedence over global values whenever you commit there.

How To Set user.name and user.email on Different Operating Systems

The commands are the same across platforms, but how you open a terminal differs.

On Windows

You might use:

• Git Bash
• Command Prompt (cmd)
• PowerShell
• The integrated terminal in an IDE like VS Code

The commands are identical:

git config --global user.name "Your Name" git config --global user.email "[email protected]" 

And for a single repo:

cd path o epo git config user.name "Your Work Name" git config user.email "[email protected]" 

On macOS and Linux

Use your regular terminal (Terminal, iTerm2, GNOME Terminal, etc.):

git config --global user.name "Your Name" git config --global user.email "[email protected]" 

Per-repo override:

cd /path/to/repo git config user.name "Your Work Name" git config user.email "[email protected]" 

Under the hood, Git saves global config in a file in your home directory (such as ~/.gitconfig), which you can also edit directly if you’re comfortable with text editors.

How To Use Multiple Identities (Work vs Personal)

Many developers need different Git identities depending on the project:

• Work repositories → corporate email and full legal name
• Personal/open-source repos → personal email or alias
• Public contributions → privacy-focused email

There are two main ways to handle this:

1. Global personal identity, local work identity

Example setup:

• Set personal identity as global:

  git config --global user.name "Alex Chen" git config --global user.email "[email protected]" 

• Override in each work repo:

  cd /path/to/work/repo git config user.name "Alex Chen" git config user.email "[email protected]" 

Pros:
Simple, explicit per-project overrides.

2. Use different global configs per machine

If you keep a separate computer for work and personal use:

• On your work machine, set your work details globally.
• On your personal machine, set your personal details globally.

Pros:
No need to remember overrides per repository; each machine has its own “default identity.”

Which approach fits better depends heavily on whether your work and personal repos are mixed on one machine, how many repos you juggle, and how strict your employer’s policies are.

Privacy, Security, and Email Choices in Git

Choosing user.email isn’t just about convenience; it can affect privacy and policy compliance.

Some considerations:

• Public repositories:
  Using your main personal or work email in public repos means that address becomes part of the permanent public history.

• Company policies:
  Some organizations require all commits to company repos to use a corporate email domain for auditing and attribution.

• Git hosting privacy:
  Platforms like GitHub can:

  • Provide a noreply email to keep your real address private while still attributing commits.
  • Allow hiding your real email from public view, while still linking commits internally.

• Single vs multiple emails:
  Using one email everywhere is simpler, but using different emails for different contexts can help you keep boundaries between work, personal projects, and public identity.

The “best” choice depends a lot on whether your repos are public or private, what your employer expects, and how sensitive you are about email exposure.

Fixing Commits Made With the Wrong Name or Email

If you’ve already made commits with incorrect user.name or user.email, updating your config won’t change those existing commits. Those commits keep the old metadata.

You have two main situations:

1. One recent, local commit is wrong
   You can amend the last commit after fixing your config:

   git config user.name "Correct Name" git config user.email "[email protected]" git commit --amend --reset-author 

   This rewrites the last commit’s author information before you push it.

2. Many commits already pushed with the wrong identity
   Fixing this usually involves history rewriting tools (like git filter-repo or older git filter-branch) and can affect anyone who has cloned the repository. It’s more advanced and requires coordination with your team.

Whether it’s worth rewriting history depends on:

• How many commits are affected
• Whether they’ve already been pushed and used by others
• How strict your organization is about commit metadata

Common Pitfalls When Configuring Git Identity

Some frequent issues you can avoid:

• Forgetting to set global config
  You may get commits with generic or missing identity until you configure it.

• Typos in the email
  A small typo (like gamil.com instead of gmail.com) can keep commits from being associated with your online profile.

• Mixing work and personal emails
  Using a personal email for work repos (or vice versa) can violate company policy or leak more information than you intend.

• Expecting old commits to update automatically
  Changing your config only affects future commits, not old ones.

How serious these issues are for you depends on whether you’re working solo, collaborating with a team, or contributing in public.

How Different Setups Change the “Right” Git Configuration

The best way to configure user.name and user.email can look very different depending on your situation:

• Solo learner on a personal laptop

  • Likely fine with one global identity.
  • Might use a personal email, possibly a privacy-friendly one.

• Professional developer in a company

  • Often needs corporate email for all company repos.
  • May still maintain a separate personal identity for open source.
  • Might use local overrides for each work vs personal repo.

• Freelancer or consultant

  • May have several clients, each with their own expectations.
  • Could use per-repo configs to reflect the appropriate branding or email per client.

• Open source contributor

  • Needs an email that hosting platforms can link to your profile.
  • Might favor a noreply email for public visibility.

• Shared or lab machines

  • System or global config might be pre-set by an admin.
  • You may need local overrides or careful checks before committing.

Each of these scenarios nudges you toward a different balance between global defaults, local overrides, and email privacy.

In the end, the commands to configure user.name and user.email are straightforward. What really matters is how you want your identity to appear across different repositories, machines, and hosting platforms—and that part depends entirely on your own setup, policies, and comfort with visibility.