Git Config File: Format, Options, and Best Practices

Introduction

Git stores configuration in plain text INI-style files. Understanding the config format and available options lets you customize Git’s behavior, manage remotes, set up aliases, and configure credentials — all from the command line or by editing the file directly.

Config File Locations

Git has three levels of configuration, each overriding the previous:

Level	File	Scope
System	`/etc/gitconfig`	All users on the machine
Global	`~/.gitconfig` or `~/.config/git/config`	Current user, all repos
Local	`.git/config`	Current repository only

# Edit global config
git config --global --edit

# Edit local repo config
git config --local --edit

# Show all config with source
git config --list --show-origin

Config File Format

The format is INI-style: sections in [brackets], key-value pairs below:

[core]
    repositoryformatversion = 0
    filemode = true
    bare = false
    logallrefupdates = true
    ignorecase = false
    precomposeunicode = true

[remote "origin"]
    url = https://github.com/username/repo-name.git
    fetch = +refs/heads/*:refs/remotes/origin/*

[branch "main"]
    remote = origin
    merge = refs/heads/main

Common Config Options

User Identity

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

[user]
    name  = Your Name
    email = [email protected]

Default Branch Name

git config --global init.defaultBranch main

Editor

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

Line Endings

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

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

Credential Storage

# Cache credentials in memory for 15 minutes
git config --global credential.helper cache
git config --global credential.helper 'cache --timeout=3600'

# Store credentials on disk (less secure)
git config --global credential.helper store

# macOS Keychain
git config --global credential.helper osxkeychain

Remote Configuration

# Single remote
[remote "origin"]
    url   = https://github.com/username/repo.git
    fetch = +refs/heads/*:refs/remotes/origin/*

# Multiple remotes (e.g., GitHub + Bitbucket)
[remote "origin"]
    url   = https://github.com/username/repo.git
    fetch = +refs/heads/*:refs/remotes/origin/*

[remote "backup"]
    url   = https://bitbucket.org/username/repo.git
    fetch = +refs/heads/*:refs/remotes/backup/*

# Add a remote
git remote add origin https://github.com/username/repo.git

# Change remote URL
git remote set-url origin https://github.com/username/new-repo.git

# List remotes
git remote -v

# Push to a specific remote
git push backup main

Branch Tracking

[branch "main"]
    remote = origin
    merge  = refs/heads/main

[branch "develop"]
    remote = origin
    merge  = refs/heads/develop
    rebase = true  # rebase instead of merge when pulling

# Set upstream for current branch
git branch --set-upstream-to=origin/main main

# Or when pushing for the first time
git push -u origin main

Aliases

Aliases let you create shortcuts for common commands:

git config --global alias.st   status
git config --global alias.co   checkout
git config --global alias.br   branch
git config --global alias.lg   "log --oneline --graph --decorate --all"
git config --global alias.undo "reset HEAD~1 --mixed"
git config --global alias.save "stash push -m"

[alias]
    st   = status
    co   = checkout
    br   = branch
    lg   = log --oneline --graph --decorate --all
    undo = reset HEAD~1 --mixed
    save = stash push -m
    # Show files changed in last commit
    last = diff HEAD~1 HEAD --name-only
    # Amend last commit without changing message
    amend = commit --amend --no-edit

Usage:

git st          # git status
git lg          # pretty log graph
git undo        # undo last commit, keep changes staged
git save "WIP"  # stash with message

Diff and Merge Tools

[diff]
    tool = vimdiff

[merge]
    tool = vimdiff
    conflictstyle = diff3

[difftool]
    prompt = false

[mergetool]
    keepBackup = false

# Use VS Code as diff/merge tool
git config --global diff.tool  vscode
git config --global difftool.vscode.cmd 'code --wait --diff $LOCAL $REMOTE'
git config --global merge.tool vscode
git config --global mergetool.vscode.cmd 'code --wait $MERGED'

Push and Pull Behavior

[push]
    default = current          # push current branch to same-named remote branch
    autoSetupRemote = true     # auto set upstream on first push (Git 2.37+)

[pull]
    rebase = false             # merge (default)
    # rebase = true            # rebase instead of merge
    # ff = only                # fast-forward only, fail if not possible

[fetch]
    prune = true               # auto-delete remote-tracking branches that no longer exist

Useful Core Settings

[core]
    editor      = vim
    autocrlf    = input        # LF on commit (macOS/Linux)
    whitespace  = fix          # fix trailing whitespace
    excludesfile = ~/.gitignore_global

[color]
    ui = auto                  # colorize output when writing to terminal

[log]
    date = relative            # show "2 days ago" instead of full date

[status]
    showUntrackedFiles = all   # show all untracked files, not just directories

Global .gitignore

# Create a global gitignore
cat > ~/.gitignore_global << 'EOF'
# macOS
.DS_Store
.AppleDouble

# Editor files
.vscode/
.idea/
*.swp
*.swo
*~

# OS
Thumbs.db
desktop.ini

# Logs
*.log
EOF

git config --global core.excludesfile ~/.gitignore_global

Bitbucket / GitHub / GitLab Config Examples

Bitbucket (HTTPS)

[remote "origin"]
    url   = https://bitbucket.org/username/repo-name.git
    fetch = +refs/heads/*:refs/remotes/origin/*

[branch "master"]
    remote = origin
    merge  = refs/heads/master

GitHub (SSH)

[remote "origin"]
    url   = [email protected]:username/repo-name.git
    fetch = +refs/heads/*:refs/remotes/origin/*

[branch "main"]
    remote = origin
    merge  = refs/heads/main

Multiple GitHub Accounts (SSH)

# ~/.ssh/config
Host github-personal
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_rsa_personal

Host github-work
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_rsa_work

# .git/config for personal repo
[remote "origin"]
    url = git@github-personal:personal-username/repo.git

# .git/config for work repo
[remote "origin"]
    url = git@github-work:work-org/repo.git

Inspecting and Editing Config

# Show a specific value
git config user.email
git config --global core.editor

# Set a value
git config --global user.name "New Name"

# Unset a value
git config --global --unset core.editor

# List all settings
git config --list

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

# Open in editor
git config --global --edit