Configuration Overview

Understanding Git’s configuration system and configuration file hierarchy

Git’s configuration system allows you to customize Git’s behavior at multiple levels. Configuration variables control everything from user identity to merge strategies, color output, and network protocols.

Configuration Files

Git reads configuration from multiple files in a specific hierarchy:

System Level

Location: /etc/gitconfig

System-wide configuration affecting all users and repositories on the machine. Requires administrator privileges to modify.

git config --system core.editor vim

Global (User) Level

Location: ~/.gitconfig or $XDG_CONFIG_HOME/git/config

User-specific configuration applying to all repositories for the current user. This is the most common place for personal settings.

git config --global user.name "Your Name"
git config --global user.email "[e-mail]"

Local (Repository) Level

Location: .git/config

Repository-specific configuration. This is the default scope when running git config inside a repository.

git config user.email "[e-mail]"

Worktree Level

Location: .git/config.worktree

Worktree-specific configuration (when extensions.worktreeConfig is enabled).

Configuration Precedence

When Git looks up a configuration value, it checks files in this order (last match wins):

1. System config (/etc/gitconfig)
2. Global config (~/.gitconfig)
3. Local config (.git/config)
4. Worktree config (.git/config.worktree)

Local settings override global settings, which override system settings.

Basic Commands

View Configuration

# List all configuration
git config --list

# List with file origins
git config --list --show-origin

# Get specific value
git config user.name

# Get value with scope
git config --global user.name

Set Configuration

# Set in local repository
git config core.ignoreCase false

# Set globally
git config --global alias.st status

# Set system-wide
git config --system core.editor nano

Unset Configuration

# Remove setting
git config --unset user.email

# Remove from global config
git config --global --unset alias.co

Edit Configuration

# Open local config in editor
git config --edit

# Open global config
git config --global --edit

# Open system config
git config --system --edit

Essential Configuration Variables

User Identity

Required for creating commits:

git config --global user.name "John Doe"
git config --global user.email "[e-mail]"

Default Editor

Set your preferred text editor:

git config --global core.editor "vim"
git config --global core.editor "code --wait"  # VS Code
git config --global core.editor "nano"

Default Branch Name

Set the default branch name for new repositories:

git config --global init.defaultBranch main

Aliases

Create shortcuts for common commands:

git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.st status
git config --global alias.last 'log -1 HEAD'

Line Endings

Configure how Git handles line endings:

# Windows: convert to CRLF on checkout, LF on commit
git config --global core.autocrlf true

# macOS/Linux: convert CRLF to LF on commit
git config --global core.autocrlf input

# Don't modify line endings
git config --global core.autocrlf false

Color Output

Enable colored output:

git config --global color.ui auto

Configuration File Syntax

Git configuration files use INI-style syntax:

[section]
    variable = value

[section "subsection"]
    variable = value

Example Configuration

[user]
    name = John Doe
    email = [e-mail]

[core]
    editor = vim
    autocrlf = input

[alias]
    co = checkout
    br = branch
    st = status
    unstage = reset HEAD --

[color]
    ui = auto

[push]
    default = simple

[pull]
    rebase = false

Conditional Includes

You can include different configuration files based on conditions:

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

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

[includeIf "onbranch:main"]
    path = ~/.gitconfig-main-branch

Use Cases

Different identities for work and personal projects:

~/.gitconfig:

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

~/.gitconfig-work:

[user]
    email = [e-mail]
    signingKey = WORK_GPG_KEY

Value Types

Boolean

True values: true, yes, on, 1
False values: false, no, off, 0, empty string

git config core.filemode true
git config core.bare false

Integer

Supports suffixes: k, M, G (1024-based)

git config core.bigFileThreshold 512M
git config pack.windowMemory 1G

String

git config user.name "John Doe"
git config core.editor "code --wait"

Color

git config color.branch.current "yellow reverse"
git config color.diff.new "green bold"

Path

Supports tilde expansion:

git config core.excludesFile ~/.gitignore_global

Best Practices

Set User Identity

Always configure user.name and user.email before making commits

Use Global for Personal Preferences

Store editor, aliases, and UI preferences in global config

Use Local for Repository-Specific Settings

Override email, hooks, or workflow settings per repository

Use Conditional Includes

Separate work and personal configurations automatically

Troubleshooting

Find Where a Setting Comes From

git config --show-origin user.email

Output:

file:/home/user/.gitconfig    [e-mail]

Check All Values for a Variable

git config --get-all user.email

Verify Configuration is Valid

git config --list

If there are syntax errors, Git will report them.

See Also

• .gitconfig Reference - Detailed configuration variables
• .gitignore - Ignore patterns for untracked files
• .gitattributes - Path-specific Git attributes