Set your username with the git config command

Your Git username is the name that appears on every commit you make. To set it, open your terminal or command prompt and run one of two commands depending on whether you want the username for just one project or all projects on your computer.

For a single project, navigate into that project's folder and run:

git config user.name "Your Name"

For all projects on your computer, add the --global flag:

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

Replace "Your Name" with whatever name you want to appear on your commits. This does not have to match your GitHub username or any other account — it is just the display name that shows up in the commit history. Git will not let you make your first commit until a username is set, so you may see an error message asking you to configure this before proceeding.

Key Takeaways

  • Use git config user.name "Your Name" to set a username for one project only.
  • Use git config --global user.name "Your Name" to set a username for all projects on your computer.
  • Your Git username is separate from your GitHub username and can be any name you choose.
  • You must set a username before Git will let you make your first commit in a new project.
  • Check what username is currently set by running git config user.name without any name after it.

The difference between global and local configuration

When you use --global, Git stores your username in a configuration file on your computer that applies to every project. This is the faster choice if you always want the same name on all your commits. The global file lives outside your project folders, so it persists across all your work.

Without --global, Git stores the username only in that one project's folder, in a hidden .git directory. Use this method if you work on projects where you need different names — for example, if you commit to a work project under your full name but a personal project under a nickname.

Local settings always override global settings. If you set a global username and then set a different local username in a project folder, Git will use the local one for commits in that folder only. This means you can have a default name for most work, then switch to a different name in specific projects without affecting the rest of your system.

Verify your username is set correctly

To check what username Git is currently using, run:

git config user.name

Git will print the name back to you. If nothing prints, the username is not set yet. This command checks the local setting first, then falls back to the global setting if no local one exists.

To see all your Git configuration settings at once, run git config --list. This shows your username, email, and other settings, along with whether each one is global or local to the current project. You can also add --show-origin to see which file each setting comes from.

Set your email address at the same time

Git also requires an email address on every commit. Set it the same way as your username:

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

Again, this does not have to be a real email address that receives mail — it is just metadata that appears in the commit history. Many people use a fake address for privacy, or a work email for work projects and a personal email for personal ones. Some developers use a format like "username+work@example.com" to keep work and personal commits organized under one email account.

If you forget to set an email, Git will refuse to let you commit and will tell you to run this command first. You can set the email globally or locally, just like the username.

Change your username later

Run the same command again with a different name to change your username at any time. The new name applies to all future commits, but does not change the name on commits you already made. This is useful if you change jobs, switch projects, or straightforward want to use a different display name.

If you need to change the name on past commits, that requires rewriting your project history, which is more complex and can cause problems if other people are working on the same project. For most purposes, it is simpler to leave old commits as they are and use the correct name going forward.

Troubleshooting common problems

If Git says "fatal: not a git repository" when you try to set a local username, you are not inside a Git project folder. Navigate into the correct folder or initialize a new Git project with git init first. Make sure you are in the root directory of your project, not a subfolder.

If your username contains spaces or special characters, wrap it in quotes, like git config user.name "Jane Doe". Without quotes, Git will only use the first word. This applies to email addresses with special characters as well.

If you set a global username but want to use a different one in a specific project, navigate into that project and run the command again without --global. The local setting will override the global one for that folder only. You can verify this worked by running git config user.name inside that project folder.

Frequently Asked Questions

Does my Git username have to match my GitHub username?

No. Your Git username is just a display name in your commit history. Your GitHub username is separate and is what you use to log in and identify your account. You can set any name you want in Git, and it will not affect your GitHub account or how your commits appear there.

Can I use different usernames for different projects?

Yes. Set a global username with --global, then navigate into any project where you want a different name and run the command again without --global. Git will use the local username for that project and the global username everywhere else.

What happens if I commit without setting a username?

Git will stop and show an error message telling you to set user.name and user.email. It will not let you commit until you do. Run the config commands, then try your commit again.

Can I see who made each commit?

Yes. Run git log to see a list of all commits in your project, including the username and email of whoever made each one. Run git log --oneline for a shorter version that shows just the commit hash and message.