git-config Tutorial

The short version

git-config is used to inspect and edit Git configuration.

When it is a good fit

• when you need to inspect and edit Git configuration
• when you want this step to be repeatable instead of ad hoc
• when you need a clearer mental model of what Git is recording or updating

Basic example

git config --global user.name "Maqi"

What to watch most closely

Learn the default behavior first. Many surprises come from adding flags before the base behavior is clear.

A safer working habit

Pair it with status, log, or diff so you can confirm what actually changed.

Useful angles for understanding it

• Understand the default behavior clearly
• Use it in day-to-day Git routines
• Reuse it safely in scripts or team habits

Related reading

Read it alongside git status, git log, and git show so it is easier to see how the command changes history, refs, the index, or the working tree.

What problem this command solves in a workflow

git config is more about repository setup, configuration, or how Git should behave by default. It may not appear every hour, but it influences whether the rest of your workflow stays stable and predictable.

Typical use cases

• Use git config when bootstrapping a repository, a machine, or a shared team default.
• Place git config into onboarding and environment validation so “works differently on my machine” issues get caught earlier.
• Use git config when debugging behavior differences that are really caused by defaults, aliases, or help/documentation gaps.

Diagram view

Foundations

Repository directoryConfig scopesHelp topics

→git config

Results

Initialized stateEffective configReference guidance

The value of this category is often not an immediate commit, but making all later commands behave more predictably.

Config priority hierarchy

Git configuration is layered. When the same key is set at multiple levels, the most specific scope wins:

1. System (/etc/gitconfig) — applies to all users on the machine
2. Global (~/.gitconfig) — applies to your user account
3. Local (.git/config) — applies to the current repository
4. Worktree (.git/worktrees/<name>/config.worktree) — applies to a specific worktree (Git 2.38+)
5. Command line (-c key=value) — overrides everything for a single command

# View where each config value comes from
git config --list --show-origin

Use --system, --global, --local, or --worktree to target a specific scope.

Common config checklist

A well-configured Git setup covers these essentials:

# Identity (required for commits)
git config --global user.name "Your Name"
git config --global user.email "you@example.com"

# Core behavior
git config --global core.editor "vim"
git config --global core.autocrlf input    # or 'true' on Windows

# Push defaults
git config --global push.default current   # or 'simple'

# Pull defaults
git config --global pull.rebase true

# Diff settings
git config --global diff.tool vscode
git config --global diff.colorMoved zebra

# Merge settings
git config --global merge.conflictstyle diff3

Conditional includes with includeIf

Git 2.13+ supports conditional configuration based on context. This is especially useful for managing separate work and personal setups:

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

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

You can also condition on branch name:

[includeIf "hasconfig:remote.*.url:git@github.com:work-org/**"]
    path = ~/.gitconfig-work

This way, commits in your work directory automatically use your work email, while personal projects use your personal email.

Git aliases

Aliases let you create shortcuts for frequently used commands:

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

# Complex aliases (prefix with ! to run shell commands)
git config --global alias.lg "log --oneline --graph --decorate --all"
git config --global alias.unstage "reset HEAD --"
git config --global alias.amend "commit --amend"
git config --global alias.wip "commit -m 'WIP'"
git config --global alias.undo "reset --soft HEAD~1"
git config --global alias.cleanup "!git branch --merged | grep -v '\\*' | xargs -n 1 git branch -d"

View all aliases:

git config --get-regexp alias

Viewing the full configuration

To see every active config value with its source:

git config --list --show-origin

This shows which file each value comes from, making it easy to track down unexpected settings. Use --show-scope to see the scope name (system, global, local, etc.) instead of file paths.

Special cases and boundaries

• Setup and config commands may not cause immediate incidents, but bad defaults can quietly distort many later commands.
• If git config affects team behavior, prefer scripts or documented defaults over relying on memory and local drift.
• When behavior disagrees with documentation, inspect config scope, aliases, and environment differences first.
• Local, global, and system config layers can all affect behavior, so troubleshooting starts by identifying which scope is actually active.