Configuration levels (system, global, local)

Configuration Levels (System, Global, Local)

Git configurations are divided into three levels: system, global, and local. Different levels apply to different scenarios and have varying priorities. Understanding the distinctions and usage of these configuration levels enables more efficient management of the Git environment.

System-Level Configuration

System-level configurations apply to all users and all repositories on the entire system. These configurations are typically stored in Git's installation directory and are suitable for setting default behaviors for all users.

View System Configuration

git config --system --list

Set System Configuration

git config --system core.autocrlf true

System-level configurations usually require administrator privileges to modify. For example, on Linux systems, the configuration file is typically located at /etc/gitconfig.

Example: Setting System-Level Line Ending Handling

sudo git config --system core.autocrlf input

This configuration instructs Git to convert line endings to LF when checking out files and to make no conversions when committing, which is suitable for Linux/Unix systems.

Global-Level Configuration

Global-level configurations apply to all repositories of the current user. These configurations are stored in the user's home directory and are suitable for setting personalized configurations for a specific user.

View Global Configuration

git config --global --list

Set Global Configuration

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

Global configuration files are typically located at:

• Linux/Mac: ~/.gitconfig
• Windows: C:\Users\Username\.gitconfig

Example: Setting Global Aliases

git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.ci commit
git config --global alias.st status

These aliases simplify the input of common Git commands. For example, you can now use git co instead of git checkout.

Local-Level Configuration

Local-level configurations apply only to the current repository. These configurations are stored in the .git/config file of the repository and are suitable for setting special configurations for a specific repository.

View Local Configuration

git config --local --list

Set Local Configuration

git config --local core.ignorecase false

Example: Setting Repository-Specific Remote URL

git config --local remote.origin.url git@github.com:username/repo.git

This configuration overrides the remote URL set in the global configuration and applies only to the current repository.

Configuration Priority

When the same configuration item is set at different levels, Git applies the configurations in the following order of priority:

1. Local configuration (highest priority)
2. Global configuration
3. System configuration (lowest priority)

Example: Viewing the Effective Value of a Specific Configuration Item

git config --show-origin user.name

This command displays the value of the user.name configuration and its source file, helping to determine the final effective configuration.

Advanced Configuration Techniques

Conditional Configuration

Git version 2.13 and above supports conditional configurations, allowing different configurations to be applied based on conditions such as repository paths.

git config --global includeIf."gitdir:~/work/".path "~/work/.gitconfig"

This configuration instructs Git to automatically load the ~/work/.gitconfig file for repositories in the ~/work/ directory.

Multiple Configuration Values

Certain configuration items can have multiple values, such as remote repository URLs:

git config --local --add remote.origin.pushurl git@github.com:username/repo.git

Configuration Inheritance

Other configuration files can be inherited using the include.path directive:

git config --global include.path ~/.gitconfig-work

Common Configuration Examples

Core Configurations

git config --global core.editor "code --wait"
git config --global core.autocrlf input
git config --global core.filemode false

Alias Configurations

git config --global alias.lg "log --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"

Diff Tool Configuration

git config --global diff.tool vscode
git config --global difftool.vscode.cmd "code --wait --diff $LOCAL $REMOTE"

Merge Tool Configuration

git config --global merge.tool vscode
git config --global mergetool.vscode.cmd "code --wait $MERGED"

Configuration File Format

Git configuration files use the INI format, and settings can be modified by directly editing the configuration files.

Global Configuration File Example

[user]
    name = John Doe
    email = john@example.com
[alias]
    co = checkout
    ci = commit
    st = status
[core]
    editor = code --wait

Local Configuration File Example

[core]
    repositoryformatversion = 0
    filemode = true
    bare = false
    logallrefupdates = true
[remote "origin"]
    url = git@github.com:username/repo.git
    fetch = +refs/heads/*:refs/remotes/origin/*
[branch "main"]
    remote = origin
    merge = refs/heads/main

Configuration Debugging

When configuration issues arise, the following command can be used for debugging:

git config --list --show-origin

This command displays all configuration items and their source files, helping to locate configuration conflicts.

Environment Variable Overrides

Git configurations can also be temporarily overridden using environment variables:

GIT_AUTHOR_NAME="Temp Name" git commit -m "Message"

This command temporarily uses "Temp Name" as the author name for the commit, without affecting the settings in the configuration files.

Version Control for Configurations

Although local configurations are stored in .git/config, it is generally not recommended to include this file in version control. Team-shared configurations can be implemented in the following ways:

1. Provide an example configuration file in the repository (e.g., .gitconfig.example)
2. Use include.path to reference shared configurations
3. Document the necessary configurations

Cross-Platform Configurations

When working across different operating systems, platform-specific configurations may be needed:

git config --global core.autocrlf true  # Windows
git config --global core.autocrlf input # Linux/Mac

Conditional configurations can be used to automatically apply platform-specific settings.

Security Configurations

Certain configurations may impact security and should be set with caution:

git config --global credential.helper cache
git config --global credential.helper 'cache --timeout=3600'

These configurations cache Git credentials, improving convenience but potentially reducing security.