Updating Git Username in Terminal: Complete Guide and Troubleshooting

Problem Background and Core Concepts

When developers change their username on GitHub website, they may encounter authentication failures when executing git push in terminal. This occurs because Git stores old username information locally and requires manual configuration updates. Git username configuration operates at multiple levels: global settings affect all repositories, local settings apply only to the current repository, and remote URLs may also contain username information.

Checking Current Configuration Status

Before making changes, it's essential to check the current Git configuration status. Use the following command to view all configuration items:

git config --list

Pay special attention to the values of user.name and user.email, which determine author information in commit records. Additionally, check remote.origin.url to verify if the remote repository URL contains the old username:

git config --get remote.origin.url

Updating User Identity Information

Git user identity includes username and email address, which can be modified using git config commands. Global modifications apply to all repositories:

git config --global user.name "new_username"
git config --global user.email "new_email@address.com"

For repository-specific modifications, navigate to the repository directory and execute:

git config user.name "new_username"
git config user.email "new_email@address.com"

After modification, use corresponding get commands to verify the configuration changes.

Updating Remote Repository URL

GitHub HTTPS URLs typically follow the format https://username@github.com/username/repo.git. After username changes, the remote repository URL needs synchronization:

git remote set-url origin https://new_username@github.com/new_username/repository_name.git

Alternatively, copy the new URL directly from the GitHub repository page. After updating, use git remote -v to verify the changes.

Credential Management and Cache Clearing

Git uses credential helpers to cache authentication information, which may cause continued use of old usernames. On Windows systems, delete old GitHub credentials through Control Panel: Control Panel > User Accounts > Credential Manager > Windows Credentials > Generic Credentials. On macOS, use Keychain Access to search and delete relevant GitHub credentials. For command-line cache, execute:

git credential-cache exit

This clears cached credentials, prompting for username and password on next operation.

Direct Configuration File Editing

Beyond git config commands, configuration files can be edited directly. The global configuration file is .gitconfig in the user home directory, where the [user] section's name and email values can be modified with a text editor. For specific repositories, edit the .git/config file in the repository directory. This approach suits batch modifications or complex configuration scenarios.

Common Issues and Solutions

After username changes, old commit records still display the original username, which is Git's expected behavior. Only new commits will use the new username. If permission denied errors occur, verify that SSH keys or access tokens match the new username. In proxy environments, proxy configurations in .gitconfig may require updates. For enterprise environments, SSH key authentication is recommended over passwords for enhanced security and convenience.

Best Practices Recommendations

After username modification, immediately test with a commit and push to ensure all configurations work correctly. For team projects, promptly notify collaborators about username changes. Regularly check Git configurations to ensure identity information matches currently used accounts. In production environments, SSH authentication is preferred to avoid storing plaintext passwords in configuration files.