You should set your Git username and email before creating commits. Git records this identity in every commit, so teammates and hosting platforms can show who authored the change.
This guide explains global and repository-specific settings, verification, privacy email addresses, multiple identities, common errors, and how to correct a recent commit.
Git username and email are not login credentials
The user.name and user.email values become commit metadata. They do not sign you in to GitHub, GitLab, Bitbucket, or another remote server. HTTPS tokens and SSH keys handle authentication separately.
Use the name you want displayed in project history. Use an email connected to your hosting account if you want commits attributed to that profile, or use the provider’s privacy email when you do not want to publish a personal address.
Check whether Git is installed
git --versionIf the command is missing, install Git with your operating system’s package manager before continuing.
Set the global Git username
git config --global user.name "Your Name"Quotes are recommended because names often contain spaces.
Set the global Git email
git config --global user.email "[email protected]"The --global scope applies to repositories for your current operating-system user unless a more specific setting overrides it.
Verify the global Git identity
git config --global user.name
git config --global user.emailList all global settings and show the file where each one comes from:
git config --global --list --show-originOn Linux and macOS, global configuration is commonly stored in ~/.gitconfig or ~/.config/git/config. Use --show-origin instead of guessing which file is active.
Set a username and email for one repository
Open the project directory:
cd /path/to/projectSet the local identity without --global:
git config user.name "Work Name"
git config user.email "[email protected]"These values are stored in the repository’s .git/config and override your global identity for this project.
Verify the effective values:
git config user.name
git config user.email
git config --list --show-originUnderstand Git configuration scopes
- System: applies to every user on the computer, usually set with
--system. - Global: applies to the current operating-system user, set with
--global. - Local: applies to one repository and is the default scope inside that repository.
- Worktree: can apply to one linked worktree when the repository enables worktree configuration.
A more specific value normally overrides a broader one. For most people, global defaults plus occasional local overrides are enough.
Find the exact Git setting in use
git config --show-origin --get user.name
git config --show-origin --get user.emailThis helps when the value looks correct globally but commits use something else. Run it inside the affected repository so local and conditional settings are included.
Use a private email address
Commit emails are stored in repository history and may become public. GitHub and some other hosting services provide a no-reply address for privacy. Copy the exact address from your account settings, then configure it:
git config --global user.email "your-provider-noreply-address"The address must match the hosting provider’s expected format if you want profile attribution. Do not invent one based on an old example.
Use different identities for work and personal projects
The simplest method is a local override in each work repository. For many repositories, Git also supports conditional includes.
Example in ~/.gitconfig:
[user]
name = Personal Name
email = [email protected]
[includeIf "gitdir:~/work/"]
path = ~/.gitconfig-workThen create ~/.gitconfig-work:
[user]
name = Work Name
email = [email protected]The directory pattern matters. Test it inside a repository under ~/work/ with git config --show-origin --get-regexp '^user\.'.
Remove a Git username or email setting
Remove a global value:
git config --global --unset user.name
git config --global --unset user.emailRemove a local repository override:
git config --unset user.name
git config --unset user.emailCheck the effective setting afterward because a broader scope may become active again.
Change the author of the latest commit
First set the correct identity, then recreate the latest commit metadata:
git config user.name "Correct Name"
git config user.email "[email protected]"
git commit --amend --reset-author --no-editThis changes the commit hash. If the commit has already been pushed, rewriting it can disrupt collaborators and may require a force push. Coordinate with the team before changing published history.
Check the author of an existing commit
git log -1 --format=fullerGit stores both author and committer identities. They can differ when one person creates a patch and another applies it.
Common Git identity errors
“Author identity unknown”
Set user.name and user.email globally or in the current repository, then retry the commit.
Commits use the wrong email
Run these commands inside the project:
git config --show-origin --get user.email
git config --list --show-origin | grep '^file:.*user\.'A local or conditional value may be overriding the global setting.
GitHub does not link the commit to my profile
Make sure the commit email is verified on the correct account or matches the exact provider no-reply address. Changing your Git configuration affects new commits; it does not automatically rewrite old ones.
Changing user.name did not change my remote login
That is expected. Commit identity and remote authentication are separate. Update the remote URL, credential helper, token, or SSH configuration as appropriate. See our guide to changing a Git remote URL.
Quick Git identity command list
# Set global defaults
git config --global user.name "Your Name"
git config --global user.email "[email protected]"
# Set identity for the current repository
git config user.name "Project Name"
git config user.email "[email protected]"
# Show effective identity and its source
git config --show-origin --get user.name
git config --show-origin --get user.email
# Inspect the latest commit
git log -1 --format=fullerFrequently asked questions
Should I use –global or local Git configuration?
Use global settings for your normal default identity. Use local settings when a particular repository needs a different work, client, or open-source identity.
Can I use any email address in Git?
Git accepts a text value, but use an address you control or an approved privacy address. Hosting platforms usually require a verified match for profile attribution.
Does Git user.name need to match my account username?
No. It is normally your display name in commit history, not the login name for the hosting platform.
Will changing Git email update old commits?
No. Configuration changes affect future commits. Rewriting old history changes commit hashes and should be planned carefully with collaborators.
Official Git references
You now know how to set your Git username and email globally or for one repository. Always verify the effective value and its source before committing, especially when you switch between personal and work projects.
Comments