Why Git needs your name and email, and how to set them

Git records who made each change to your code by storing a name and email address with every commit. This is how your team knows who wrote what, and how Git can attribute work to you across projects. Before you make your first commit, you need to tell Git who you are by configuring user.name and user.email.

These settings live in a configuration file on your computer. You can set them globally (so every project uses the same name and email) or locally (so a single project uses different credentials). Most people set them globally once and never think about it again.

Key Takeaways

  • Git requires a name and email address before you can commit code, and these are recorded permanently in your project history.
  • The global configuration file stores settings that apply to every Git project on your computer, while local configuration overrides the global settings for a single project.
  • Use git config --global user.name "Your Name" and git config --global user.email "your.email@example.com" to set up Git the first time.
  • You can verify your settings at any time by running git config user.name and git config user.email without the assignment part.
  • If you need different credentials for work and personal projects, you can override the global settings with local configuration in a specific folder.

Setting your name and email globally

Global configuration applies to every Git project on your computer. Open your terminal or command prompt and run these two commands, one after the other:

git config --global user.name "Your Name"

git config --global user.email "your.email@example.com"

Replace "Your Name" with your actual name (keep the quotes) and "your.email@example.com" with your actual email address. This is the name and email that will appear on all your commits unless you override them later in a specific project.

Git stores this information in a hidden file called .gitconfig in your home directory. You do not need to edit this file directly — the commands above do it for you.

Checking what you have configured

After you set your name and email, verify that Git recorded them correctly. Run these commands:

git config user.name

git config user.email

Each command will print back what you set. If you see your name and email address, you are done with the global setup. If you see nothing, the configuration did not save — try running the setup commands again and check for typos.

You can also see all your Git configuration settings at once by running git config --list. This shows both global and local settings, so it is useful if you have overridden settings in a specific project.

Using different credentials for different projects

Sometimes you need different credentials for different work. For example, you might use your personal email for open-source projects but your work email for your employer's repositories. You can override the global settings in a single project by using local configuration.

Navigate to the project folder in your terminal and run the same commands without the --global flag:

git config user.name "Work Name"

git config user.email "work.email@company.com"

Now every commit you make in this folder will use the local credentials, while commits in other projects will use your global settings. The local configuration is stored in a file called config inside the .git folder of that project, and it overrides the global settings only for that project.

What happens if you commit without setting your name and email

If you try to make a commit before configuring Git, you will see an error message telling you to set user.email and user.name. Git will not let you commit until you provide this information. The error message usually includes the exact commands you need to run.

Some systems have a fallback: if Git cannot find your configuration, it may try to use your system username and a default email address. This almost never produces the result you want, so it is better to set your credentials explicitly from the start.

Fixing a mistake in your name or email

If you set the wrong name or email, you can change it by running the configuration commands again with the correct information. The new setting will overwrite the old one immediately.

Keep in mind that changing your configuration only affects commits you make from that point forward. Commits you already made will keep the old name and email. If you need to change the author on commits that are already in your history, that requires a more complex operation that rewrites your project history — something to avoid unless you have a strong reason.

Frequently Asked Questions

Does my email address have to be real?

Git does not validate your email address, so technically you could enter anything. However, if you are working with a team or pushing to a shared repository, use a real email address so your teammates can contact you if they have questions about your code.

Can I use a different name and email for each commit?

You can, but you would have to reconfigure Git before each commit, which is impractical. Use local configuration if you need different credentials for different projects, or use global configuration if you want the same credentials everywhere.

What if I am using GitHub or another Git hosting service?

The name and email you configure in Git are separate from your GitHub account username and password. Git uses the name and email to mark who made each commit, while GitHub uses your account credentials to verify that you have permission to push to a repository. You can set any name and email in Git, but GitHub will match commits to your account based on the email address you registered with GitHub.

Will changing my Git configuration affect commits I already made?

No. Changing your configuration only affects new commits going forward. Old commits keep the name and email that was configured when you made them. If you need to change the author on existing commits, you would need to rewrite your project history, which is a separate and more involved process.