Git Config Configuration Management Complete Guide: Practical Techniques for Viewing, Deleting, and Fixing

Applicable scenarios: When you encounter Git configuration confusion (such as an incorrect username, email conflict, invalid keys such as user.username residue), this article will provide a complete solution from inspection to repair.

In daily development, we often encounter messy Git configuration issues—wrong email, duplicate usernames, or extra invalid configurations (such as user.username). This article will systematically explain techniques for viewing, deleting, and repairing Git configuration based on real-world scenarios.

I. Understanding the three levels of Git configuration

Git configuration is divided into three levels, with priority from low to high as follows:

Level	Scope	Configuration file path	Command parameters	Remarks
system-level	All users on the entire computer	$(prefix)/etc/gitconfig	--system	⚠️ Default Does not exist, must be created manually
Global level	Current operating system user	~/.gitconfig	--global	✅ Most commonly used; recommended to configure here
Local level	Current Git repository only	仓库根目录/.git/config	--local(Default)	✅ Each repository is independent and overrides the global configuration

About system-level configuration (most people don't need it)

• Does not exist by default: Whether on macOS or Linux, Git does not automatically create a system-level configuration file, so it is normal that you cannot find it.

• Under what circumstances is it needed?: Only when you need to for All users(For example, company shared development machines) only need to be created manually when configuring them uniformly.

• Individual developer: Completely ignore system-level configuration, use --global and --local That's enough.

Priority rules

Local level > Global level > System level When the same configuration item exists at multiple levels, the higher priority overrides the lower.

II. View Configuration Information

2.1 View all configurations

# View all active configurations (grouped by file source)
git config --list

# View only the local configuration of the current repository.
git config --list --local

# View global configuration only
git config --list --global

# View system-level configuration only (if the file does not exist, output is empty)
git config --list --system

2.2 View specific configuration items

# View username
git config user.name

# Check email
git config user.email

# View remote repository address
git config remote.origin.url

# View proxy settings
git config http.proxy

2.3 View the source file of the configuration (a great troubleshooting tool!)

When you find that a certain configuration exists "like a ghost" but you can't find where to set it, this command is the most useful:

# View all configurations and their source files
git config --list --show-origin

# View a specific configuration item and its source file (note: the key must be specified)
git config --show-origin user.name

Output example:

file:/Users/fishfinal/.gitconfig   user.name=fishfinal
file:.git/config                   [email protected]

This will clearly tell you which file each configuration comes from, making it easy to pinpoint the source.

Special Attention

--show-origin Must be used in conjunction with --list or specify a specific key to use, when used alone, it will display help information!

# ❌ Incorrect usage (will display help information)
git config --show-origin

# ✅ Correct usage
git config --list --show-origin
git config --show-origin user.name

3. Delete the incorrect configuration

Scenario reproduction

The following content appears in your configuration:

user.email[email protected]
user.username=fishfinal    # ❌ Invalid configuration, Git does not recognize it
user.name=fishfinal

Note:user.username Yes Invalid key, Git will not read it, so you can safely delete it.

3.1 Precisely delete a single configuration item (recommended)

# Delete invalid items in the global configuration
git config --global --unset user.username

# Remove invalid entries from the local configuration.
git config --local --unset user.username

# If the same key appears multiple times (for example, duplicate settings), use --unset-all
git config --global --unset-all user.username

3.2 Directly Edit the Configuration File (Visual Operation)

# Edit global configuration
git config --global -e

# Edit the current repository configuration
git config --local -e

This will open the configuration file in the default editor (such as Vim or VS Code); just find the corresponding line and delete it directly.

Note

If running --unset an error is reported at that time error: key does not contain a section: user.username, indicating that this configuration may have been incorrectly written in [user] Outside the paragraph, at this moment Must be manually deleted using the editor..

3.3 Batch delete all configurations of a paragraph

# Delete the entire [user] section (use with caution!)
git config --local --remove-section user

# Delete the [user] section in the global configuration
git config --global --remove-section user

IV. Corrected Configuration

4.1 Delete first, then modify (recommended)

# Clear the erroneous configuration first.
git config --global --unset user.name
git config --global --unset user.email

# Then set the correct value.
git config --global user.name "fishfinal"
git config --global user.email "[email protected]"

4.2 Forced Overwrite

Use it directly --replace-all Force overwrite all configurations with the same name:

git config --global --replace-all user.name "fishfinal"
git config --global --replace-all user.email "[email protected]"

V. Common Configuration Troubleshooting Checklist

Problem symptoms	Troubleshooting commands	Solution
The commit record shows an incorrect username.	git config user.name	Reset user.name
Prompt when pushing 403 Permission error	`git config --list	grep url`
Newline characters cause diff confusion	git config core.autocrlf	According to OS settings input/true/false
Unable to pull due to proxy settings	`git config --list	grep proxy`
Too many configurations; can't tell where they come from.	git config --list --show-origin	Manually clean up after locating the specific files.

VI. Best Practice Recommendations

6.1 Global Configuration (Recommended Settings)

git config --global user.name "your name"
git config --global user.email "[email protected]"
git config --global core.editor "code --wait"   # Use VS Code as the editor
git config --global init.defaultBranch main
git config --global pull.rebase false           # Maintain merge behavior

6.2 Project-level configuration (overrides global)

If you use different email addresses for company projects and personal projects:

# Execute after entering the project directory
git config --local user.email "[email protected]"

6.3 Periodic Review Configuration

It is recommended to run a configuration review every six months:

# View all configurations and audit
git config --list --show-origin | less

# Check for suspicious or outdated configurations
git config --list | grep -E "proxy|user|core"

VII. Quick Reference Table

Operation	command	Description
View all configurations	git config --list	Display all effective configurations
View all configurations and sources	git config --list --show-origin	Show which file each configuration comes from.
View individual configuration	git config <key>	As git config user.name
View single-item configuration and source	git config --show-origin <key>	⚠️ Must specify key
Settings Configuration (Global)	git config --global <key> <value>	Recommended for use
Settings Configuration (Local)	git config --local <key> <value>	Only effective for the current repository
Delete single-item configuration	git config --global --unset <key>	Delete the specified configuration item
Delete all configurations with the same name.	git config --global --unset-all <key>	Used when there are multiple configurations with the same name
Edit configuration file	git config --global -e	Open the configuration file with an editor.
Delete the entire paragraph.	git config --local --remove-section <section>	as --remove-section user

VIII. Advanced Techniques

8.1 Configure Aliases (Alias)

By configuring aliases, you can greatly improve Git command efficiency:

# Set common aliases
git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.st status
git config --global alias.lg "log --oneline --graph --all"

Once configured, you can use the abbreviation:

git st          # Instead of git status
git co main     # Instead of git checkout main
git lg          # Replace git log --oneline --graph --all

8.2 Conditional Configuration (Conditional Includes)

Git 2.13+ supports loading different configurations based on path conditions, which is very suitable for managing multi-account scenarios:

at ~/.gitconfig Configure in:

[includeIf "gitdir:~/work/"]
    path = ~/.gitconfig-work
[includeIf "gitdir:~/personal/"]
    path = ~/.gitconfig-personal

~/.gitconfig-work Content:

[user]
    name = Zhang San
    email = [email protected]

~/.gitconfig-personal Content:

[user]
    name = fishfinal
    email = [email protected]

In this way, when you are ~/work/ When in the directory, the company email configuration will be loaded automatically; in ~/personal/ Next time, use your personal email; no manual switching is required.

8.3 Canceling Hierarchical Overrides of Configuration

If you want to "cancel" a local configuration and make it revert to using the global configuration value:

# Delete the local configuration so that it reverts to the global configuration.
git config --local --unset user.email

Nine. Common Misconceptions

Misconception	Correct understanding
System-level configuration exists by default.	❌ Does not exist by default; manual creation is required
The more configuration, the better.	✅ Keep the configuration lean and set only the necessary items.
user.username is a valid configuration	❌ Git only recognizes user.name and user.email
Must use --global only then will it take effect	✅--local Only effective for the current repository, with higher priority.
I messed up the configuration, so I can only reinstall Git.	✅ Use --unset or delete it in the editor to fix it
--show-origin Can be used alone	❌ Must be used together with --list or specify key

Reference Links

• Git Official Documentation - git-config

• Pro Git - Customizing Git

• Git Official Documentation - Conditional Includes