Skip to main content
The .gitconfig file contains configuration variables that control Git’s behavior. This reference covers the most commonly used configuration options.

​
File Format

Git configuration files use an INI-style format with sections and variables: 
[section]
    variable = value
    
[section "subsection"]
    variable = value

​
Syntax Rules

  • Section names are case-insensitive
  • Variable names are case-insensitive
  • Comments start with # or ;
  • Values can be quoted with double quotes
  • Lines can be continued with backslash \

​
Example

# Core configuration
[core]
    filemode = false
    # Editor setting
    editor = vim
    
[diff]
    external = /usr/local/bin/diff-wrapper
    renames = true
    
[branch "devel"]
    remote = origin
    merge = refs/heads/devel

​
User Identity

Your name for commit author information.
git config --global user.name "John Doe"
Configuration:
[user]
    name = John Doe
Your email address for commit author information.
git config --global user.email "john@example.com"
Configuration:
[user]
    email = john@example.com
GPG key ID for signing commits and tags.
git config --global user.signingKey 1A2B3C4D
For SSH signing:
git config --global user.signingKey ~/.ssh/id_ed25519.pub
Require user.email and user.name to be configured explicitly.
git config --global user.useConfigOnly true
Prevents Git from guessing identity, useful when managing multiple identities.

​
Core Settings

Default text editor for commit messages and interactive operations.
# Vim
git config --global core.editor vim

# VS Code (wait for window to close)
git config --global core.editor "code --wait"

# Nano
git config --global core.editor nano

# Sublime Text
git config --global core.editor "subl -n -w"
Line ending conversion behavior.
# Windows: convert LF to CRLF on checkout, CRLF to LF on commit
git config --global core.autocrlf true

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

# No conversion
git config --global core.autocrlf false
Values:
  • true - Convert to CRLF on checkout, to LF on commit
  • input - Convert to LF on commit only
  • false - No conversion
Track executable bit changes in file permissions.
git config core.filemode false
Set to false on filesystems that don’t preserve executable permissions (like FAT32, some Windows systems).
Treat filenames as case-insensitive.
git config core.ignoreCase true
Automatically set by git init on case-insensitive filesystems (APFS, HFS+, NTFS).
Global gitignore file for all repositories.
git config --global core.excludesFile ~/.gitignore_global
Configuration:
[core]
    excludesFile = ~/.gitignore_global
Program to use for paginated output.
# Use less with specific options
git config --global core.pager "less -FRX"

# Disable pager
git config --global core.pager cat

​
Aliases

Create shortcuts for Git commands: 
# Simple 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

# Complex aliases
git config --global alias.unstage 'reset HEAD --'
git config --global alias.last 'log -1 HEAD'
git config --global alias.visual '!gitk'
Configuration file: 
[alias]
    co = checkout
    br = branch
    ci = commit
    st = status
    unstage = reset HEAD --
    last = log -1 HEAD
    lg = log --oneline --decorate --all --graph
    
    # Shell command (starts with !)
    visual = !gitk

​
Shell Aliases

Aliases starting with ! execute as shell commands: 
[alias]
    # Run gitk
    visual = !gitk --all
    
    # Complex shell command
    praise = !git log --pretty=format:'%h %an: %s' --author

​
Branch Settings

Default branch name for new repositories.
git config --global init.defaultBranch main
Automatically set up tracking for new branches.
git config --global branch.autoSetupMerge always
Values:
  • true - Set up tracking when branching from remote branch
  • always - Set up tracking for all new branches
  • false - Never set up tracking automatically
Default remote for a specific branch.
git config branch.main.remote origin
Default merge target for a specific branch.
git config branch.main.merge refs/heads/main

​
Color Configuration

Enable colored output globally.
git config --global color.ui auto
Values:
  • auto - Use colors when output is to a terminal
  • always - Always use colors
  • never - Never use colors
Customize colors for different output types:
# Branch colors
git config --global color.branch.current "yellow reverse"
git config --global color.branch.local yellow
git config --global color.branch.remote green

# Diff colors
git config --global color.diff.meta "yellow bold"
git config --global color.diff.frag "magenta bold"
git config --global color.diff.old "red bold"
git config --global color.diff.new "green bold"

# Status colors
git config --global color.status.added green
git config --global color.status.changed yellow
git config --global color.status.untracked red
Configuration:
[color "branch"]
    current = yellow reverse
    local = yellow
    remote = green

[color "diff"]
    meta = yellow bold
    frag = magenta bold
    old = red bold
    new = green bold

​
Merge and Diff Settings

Default merge tool for resolving conflicts.
git config --global merge.tool vimdiff
git config --global merge.tool meld
git config --global merge.tool vscode
Conflict marker style.
# Show common ancestor in conflicts
git config --global merge.conflictStyle diff3

# Standard two-way diff
git config --global merge.conflictStyle merge
Default diff tool.
git config --global diff.tool vimdiff
git config --global diff.tool meld
Diff algorithm to use.
git config --global diff.algorithm histogram
Values: myers, minimal, patience, histogram

​
Push and Pull Settings

Default push behavior.
git config --global push.default simple
Values:
  • simple - Push current branch to upstream (default)
  • current - Push current branch to branch of same name
  • upstream - Push to configured upstream
  • matching - Push all matching branches
  • nothing - Require explicit refspec
Automatically create remote tracking branches.
git config --global push.autoSetupRemote true
Use rebase instead of merge when pulling.
git config --global pull.rebase true
Values:
  • true - Rebase when pulling
  • false - Merge when pulling (default)
  • interactive - Interactive rebase
  • merges - Rebase and preserve merge commits
Fast-forward behavior when pulling.
git config --global pull.ff only
Values:
  • true - Fast-forward when possible
  • false - Always create merge commit
  • only - Only allow fast-forward

​
Credential Settings

Credential storage helper.
# Cache credentials in memory (15 minutes)
git config --global credential.helper cache

# Cache with custom timeout (1 hour)
git config --global credential.helper 'cache --timeout=3600'

# Store credentials in file (plaintext)
git config --global credential.helper store

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

# Windows Credential Manager
git config --global credential.helper manager

​
Remote Settings

URL for a remote repository.
git config remote.origin.url https://github.com/user/repo.git
Fetch refspec for a remote.
git config remote.origin.fetch '+refs/heads/*:refs/remotes/origin/*'

​
Advanced Settings

Sign all commits with GPG.
git config --global commit.gpgSign true
Sign all tags with GPG.
git config --global tag.gpgSign true
Enable reuse of recorded conflict resolutions.
git config --global rerere.enabled true
Auto-correct typos after delay (in deciseconds).
# Wait 2 seconds before running corrected command
git config --global help.autoCorrect 20

​
Include Directives

​
Static Includes

[include]
    path = /path/to/other.gitconfig
    path = ~/.gitconfig-common

​
Conditional Includes

Include configuration based on repository location.
# Include for all repos in ~/work/
[includeIf "gitdir:~/work/"]
    path = ~/.gitconfig-work

# Include for specific project
[includeIf "gitdir:/path/to/project/.git"]
    path = ~/.gitconfig-project
Include configuration based on current branch.
[includeIf "onbranch:main"]
    path = ~/.gitconfig-main

[includeIf "onbranch:feature/*"]
    path = ~/.gitconfig-feature

​
Common Configuration Examples

​
Minimal Setup

[user]
    name = John Doe
    email = john@example.com

[init]
    defaultBranch = main

[core]
    editor = vim

​
Developer Setup

[user]
    name = John Doe
    email = john@example.com
    signingKey = 1A2B3C4D

[init]
    defaultBranch = main

[core]
    editor = code --wait
    autocrlf = input
    excludesFile = ~/.gitignore_global

[alias]
    co = checkout
    br = branch
    ci = commit
    st = status
    unstage = reset HEAD --
    last = log -1 HEAD
    lg = log --oneline --decorate --all --graph

[color]
    ui = auto

[pull]
    rebase = true

[push]
    default = simple
    autoSetupRemote = true

[commit]
    gpgSign = true

[rerere]
    enabled = true

​
Work/Personal Split

~/.gitconfig: 
[user]
    name = John Doe

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

[includeIf "gitdir:~/personal/"]
    path = ~/.gitconfig-personal
~/.gitconfig-work: 
[user]
    email = john.doe@company.com
    signingKey = WORK_GPG_KEY
~/.gitconfig-personal: 
[user]
    email = john@personal.com
    signingKey = PERSONAL_GPG_KEY

​
See Also