The two places you need to set a username in Git

Git stores your username in two separate locations, and they do different things. Your global username is what Git uses for every repository on your computer unless you override it. Your local username is specific to one folder and overrides the global setting for that project only. Most people set the global username once and never touch it again. You set a local username only if you work on a project under a different name — for instance, if you contribute to open-source work under a pseudonym but commit to work projects under your real name.

Both usernames are stored as plain text in configuration files on your hard drive. They are not connected to your GitHub account, GitLab account, or any online service. You can set them to anything you want. Git does not verify that the name you enter is real or that it matches any account anywhere.

Key Takeaways

  • Set your global username once with git config --global user.name "Your Name", and Git will use it for all repositories unless you override it.
  • Set a local username for a single project by running git config user.name "Your Name" inside that folder, without the --global flag.
  • Check what username Git will use for your next commit by running git config user.name in the folder where you are working.
  • Your Git username is separate from your GitHub or GitLab login and does not have to match it, though matching them makes your commit history clearer.

Setting your global username from the command line

Open the terminal or command prompt on your computer. On Mac, search for "Terminal" in Spotlight. On Windows, search for "Command Prompt" or "PowerShell". On Linux, open your terminal process.

Type this command and press Enter, replacing "Your Name" with the name you want to appear in your commit history:

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

Git will not print a confirmation message. That is normal. The setting has been saved. If you want to verify it worked, type git config --global user.name and press Enter. Git will print back the name you just set.

Setting a username for one project only

Navigate to the folder where your project lives. In the terminal, use the cd command to move into that directory. For example, if your project is in a folder called my-website on your Desktop, type:

cd ~/Desktop/my-website

Once you are inside the project folder, type this command with your chosen name:

git config user.name "Your Name"

Notice there is no --global flag this time. This sets the username only for this project. When you commit inside this folder, Git will use this name. When you commit in any other folder on your computer, Git will use your global username instead.

Checking which username Git will use

Before you make your first commit in a folder, you can see which username Git will use. Type this command:

git config user.name

Git will print the username it will use for your next commit in that location. If you have set a local username in that folder, it will print that. If you have not, it will print your global username. If you have not set either one, Git will print nothing, and your next commit will fail with an error message asking you to set a username.

What happens if you do not set a username

If you try to commit without setting a username anywhere, Git will stop and show an error. The error message tells you to run git config user.name and git config user.email to set them. You cannot commit until you do.

If you have set a global username but are working in a folder where you want a different name, set a local username in that folder. The local setting will take priority for all commits you make there.

Changing a username you already set

To change your global username, run the same command you used to set it the first time:

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

Git will overwrite the old name with the new one. To change a local username for a specific project, navigate into that project folder and run the same command without the --global flag. This will not affect your global username or any other project.

Changing your username does not change the names attached to commits you have already made. Old commits will still show the name that was set when you made them. Only new commits will use the new name.

Why your Git username is separate from your online account

When you push commits to GitHub, GitLab, or another hosting service, that service matches your commits to your account using your SSH key or login credentials, not your Git username. Your Git username is just a label that appears in the commit history. You can set it to anything, and it will not affect which account receives credit for the commit online.

However, most people set their Git username to match their real name or their account name on the hosting service. This makes the commit history easier to read and prevents confusion about who wrote what code. If you work on multiple projects under different identities, set a different local username in each folder.

Frequently Asked Questions

Can I use a fake name or pseudonym as my Git username?

Yes. Git does not verify usernames. You can set it to anything you want. However, if you push to GitHub or another service, that service will match commits to your account based on your login, not your username. Your chosen name will appear in the commit history, but the service will know who actually made the commit.

Do I need to set an email address too?

Yes. Git requires both a username and an email address for commits. Set your email the same way you set your username, using git config --global user.email "your.email@example.com". The email does not have to be real, but most people use their actual email so commits can be traced back to them.

What if I set my username wrong and want to change all my old commits?

Changing the author name on commits you have already made is possible but complicated and can cause problems if you have pushed those commits to a shared repository. For a single project you have not shared, you can use git rebase to rewrite history. For commits you have already pushed, talk to your team before making changes. It is usually easier to set the correct username going forward and leave old commits as they are.

Does my Git username have to match my GitHub username?

No. GitHub matches commits to your account using your SSH key or login credentials, not your username. You can set your Git username to your real name, your GitHub username, or anything else. Matching them is a good practice for clarity, but it is not required.