git config Levels: System, Global, Local, and Worktree Config Precedence

Q: What are the four levels of Git configuration?

System (applies to every user and repository on a machine), global (applies to all of your repositories), local (applies to just one specific repository), and worktree (applies to just one specific worktree, the most specialized level).

Q: Which configuration level wins if the same setting is defined at multiple levels?

The most specific applicable level always wins. Local overrides global, which overrides system, and worktree (if enabled and set) overrides all three, following the precedence order system < global < local < worktree.

Q: What is worktree-level configuration, and why does it require extra setup?

It's the most specialized configuration level, letting a setting apply to just one specific worktree (from Module 7) of a repository rather than the whole repository. It requires an explicit opt-in, running git config extensions.worktreeConfig true, before Git will recognize or apply any worktree-specific settings.

Q: Is worktree-level config something I need to use regularly?

No, it's a fairly specialized feature, mainly relevant in advanced scenarios where you need genuinely different settings across different worktrees of the same repository. Most everyday configuration needs are fully covered by the system, global, and local levels.

Module 1 introduced three levels of Git configuration — system, global, and local — as part of the very first practical lesson in this course. Now, with Module 7's worktree feature already covered, this lesson completes the full picture: a fourth, more specialized worktree-level config, and the exact, complete precedence order governing all four.

Learning Objectives

Recall the three configuration levels from Module 1: system, global, and local.
Understand the fourth level, worktree config, and when it's useful.
State the complete precedence order across all four levels.
Use git config --show-origin to determine exactly which file a given setting comes from.

Key Terms to Know Before Learning Git Config Levels

System-level config: Settings applying to every user and every repository on a machine, stored in a system-wide file.
Global-level config: Settings applying to all repositories for the current user, stored in ~/.gitconfig.
Local-level config: Settings applying only to one specific repository, stored in that repository's .git/config.
Worktree-level config: Settings applying only to a single specific worktree (Module 7), the most specific and narrowly scoped level, requiring an explicit opt-in setting to enable.

How Git Config Levels and Precedence Actually Work

Recall Module 1's three levels: **system** (every user, every repository on the machine), **global** (all repositories for the current user, in `~/.gitconfig`), and **local** (one specific repository, in that repository's `.git/config`), with more specific levels overriding broader ones.

Now that Module 7 has introduced `git worktree` — multiple working directories sharing one underlying repository — a fourth, even more specific level becomes relevant: **worktree-level config**. This allows a setting to apply to only **one specific worktree**, distinct from the repository's shared local config, useful in the fairly specialized scenario where you genuinely need different configuration behavior across different worktrees of the same underlying repository (for example, different `core.sparseCheckout` settings per worktree, a more advanced use case beyond this course's scope, but a real reason this level exists). Unlike the other three levels, worktree-level config requires an explicit opt-in — running `git config extensions.worktreeConfig true` for a repository — before Git will recognize and apply worktree-specific settings at all, reflecting how specialized and rarely needed this particular level is in everyday use.

The **complete precedence order**, from least to most specific (each level overriding the ones before it):

```
system < global < local < worktree
```

The most specific applicable level always wins for any given setting. If `user.email` is set at the global level (your personal default) but also explicitly set at the local level for one particular repository (perhaps a work-specific email, exactly the scenario from Module 1's original lesson), the local setting wins for that repository, while the global setting continues to apply everywhere else where no more specific override exists.

When a setting behaves unexpectedly, and you're unsure which level is actually responsible, `git config --list --show-origin` (touched on briefly in Module 1) is the definitive diagnostic tool — it lists every active setting, precisely annotated with which specific file it came from:

```
git config --list --show-origin
```

This directly resolves the otherwise-confusing situation of a setting seeming to have 'the wrong value' when multiple levels are actually involved, by showing you exactly which file is actually responsible for the value currently in effect.

Git Config Precedence: Visual Walkthrough

Draw four concentric boxes, largest to smallest, labeled from outside in: 'System (--system): every user, every repo on the machine', 'Global (--global): current user, all their repos (~/.gitconfig)', 'Local (--local, default inside a repo): one specific repository (.git/config)', 'Worktree (--worktree): one specific worktree of a repo, requires explicit opt-in (extensions.worktreeConfig)'. Draw an arrow labeled 'increasing precedence — most specific wins' pointing from the outer box to the innermost box.

Git Config Levels: Quick Reference Table

Level	Flag	Scope	File Location
System	--system	Every user, every repository on the machine	/etc/gitconfig (varies by OS)
Global	--global	Current user, all their repositories	~/.gitconfig
Local	--local (default inside a repo)	One specific repository	.git/config
Worktree	--worktree	One specific worktree only (requires opt-in)	.git/worktrees/<name>/config.worktree

git config Levels: Command Syntax and Examples

# Recall the first three levels from Module 1
git config --global user.email "asha@personal.com"
git config --local user.email "asha@company.com"   # overrides global, for THIS repo only

# Enable and use the fourth, worktree-specific level (Module 7's worktree feature)
git config extensions.worktreeConfig true   # required opt-in
git config --worktree core.sparseCheckout true   # applies to just THIS worktree

# Diagnose exactly which file is responsible for a given setting
git config --list --show-origin | grep user.email
# file:~/.gitconfig               user.email=asha@personal.com
# file:.git/config                user.email=asha@company.com   <- this one WINS (more specific)

Breaking Down the Git Config Levels Example

The first two lines recreate Module 1's classic example: a personal email set globally, overridden locally for one specific repository (like a work project). The worktree example demonstrates the required opt-in step (`extensions.worktreeConfig true`) before Git recognizes worktree-level settings at all, followed by an actual worktree-specific config value. The final `--show-origin` command resolves any ambiguity directly, listing both the global and local `user.email` entries side by side with their exact source files, making it immediately clear which one is actually in effect for this repository (the more specific local one, per the precedence order).

How Git Config Levels Are Used on Real Engineering Teams

Developers working across both personal open-source projects and a company's private repositories commonly rely on exactly the global-vs-local email override pattern from Module 1, now understood as one instance of the complete four-level precedence system.
Worktree-level config remains a fairly specialized, less commonly needed feature, generally only relevant to advanced workflows involving git worktree (Module 7) combined with per-worktree settings like sparse checkout configurations.
System-level config is typically managed by IT/DevOps teams provisioning company-issued developer machines, setting baseline defaults (like a corporate proxy setting) that apply across every user and repository on that machine.
git config --list --show-origin is a genuinely common, practical troubleshooting step whenever a Git setting behaves unexpectedly on a machine with configuration spread across multiple levels.

git config Levels Interview Questions and Answers

Q1. What are the four levels of Git configuration, from least to most specific?

System (every user, every repository on the machine), global (all repositories for the current user), local (one specific repository), and worktree (one specific worktree of a repository, requiring an explicit opt-in setting to enable). Each level overrides the ones before it in this order.

Q2. How would you determine exactly which configuration file is responsible for a specific setting's current value?

Run git config --list --show-origin, which lists every currently active setting annotated with the exact file it came from, letting you see precisely which level (system, global, local, or worktree) is actually responsible for the value in effect, especially useful when multiple levels define the same setting differently.

Q3. What is unique about worktree-level configuration compared to the other three levels?

Unlike system, global, and local, which are always available, worktree-level config requires an explicit opt-in (git config extensions.worktreeConfig true) before Git will recognize and apply worktree-specific settings at all. It's also the most specific and narrowly scoped level, applying to only one particular worktree of a repository rather than the whole repository.

git config Levels Quiz: Test Your Understanding

1. What is the correct precedence order of Git's four configuration levels, from least to most specific?

Local, global, system, worktree
System, global, local, worktree
Worktree, local, global, system
Global, system, worktree, local

Answer: B. System, global, local, worktree

Explanation: System is the broadest level, followed by global (per-user), then local (per-repository), with worktree being the most specific, narrowly scoped level, each overriding the ones before it.

2. What must be done before Git will recognize worktree-level configuration at all?

Nothing — it's available by default like the other three levels
Running git config extensions.worktreeConfig true as an explicit opt-in
Creating at least two worktrees first
Upgrading to a paid version of Git

Answer: B. Running git config extensions.worktreeConfig true as an explicit opt-in

Explanation: Unlike system, global, and local config, worktree-level configuration requires this explicit opt-in setting before Git will recognize and apply worktree-specific settings.

3. Which command shows exactly which configuration file is responsible for each currently active setting?

git config --list
git config --list --show-origin
git status --config
git log --config

Answer: B. git config --list --show-origin

Explanation: Adding --show-origin to git config --list annotates each active setting with the exact file it came from, resolving ambiguity when multiple configuration levels define the same setting.

Common Mistakes With Git Config Levels

Forgetting worktree-level config exists entirely, or attempting to use it without first enabling the required extensions.worktreeConfig opt-in.
Assuming a setting's value comes from global config when it's actually been overridden more specifically at the local (or worktree) level, without checking --show-origin to confirm.
Confusing the precedence direction — assuming a broader level (like system) would override a narrower one (like local), when it's actually the reverse.
Not realizing this four-level system is the same underlying mechanism first introduced in Module 1, just now completed with the worktree addition relevant after learning about worktrees in Module 7.

git config Levels: Exam-Ready Quick Notes

Four levels, least to most specific: system < global < local < worktree.
Most specific applicable level always wins for a given setting.
Worktree-level requires explicit opt-in: git config extensions.worktreeConfig true.
git config --list --show-origin: definitive tool for diagnosing exactly which file/level is responsible for a setting's current value.

git config Levels: Key Takeaways

Git configuration operates across four levels of increasing specificity: system, global, local, and worktree, each overriding the ones before it.
Worktree-level config is the most specialized, requiring an explicit opt-in and relevant only in fairly advanced scenarios involving Module 7's git worktree feature.
git config --list --show-origin is the definitive diagnostic tool whenever a setting's actual source across multiple levels is unclear.

Frequently Asked Questions About Git Config Levels

Q1. What are the four levels of Git configuration?

System (applies to every user and repository on a machine), global (applies to all of your repositories), local (applies to just one specific repository), and worktree (applies to just one specific worktree, the most specialized level).

Q2. Which configuration level wins if the same setting is defined at multiple levels?

The most specific applicable level always wins. Local overrides global, which overrides system, and worktree (if enabled and set) overrides all three, following the precedence order system < global < local < worktree.

Q3. What is worktree-level configuration, and why does it require extra setup?

It's the most specialized configuration level, letting a setting apply to just one specific worktree (from Module 7) of a repository rather than the whole repository. It requires an explicit opt-in, running git config extensions.worktreeConfig true, before Git will recognize or apply any worktree-specific settings.

Q4. How can I figure out which configuration file is actually responsible for a specific setting's value?

Run git config --list --show-origin, which lists every currently active setting along with the exact file it came from, making it easy to see which level is actually in effect, especially when a setting seems to have an unexpected value.

Q5. Is worktree-level config something I need to use regularly?

No, it's a fairly specialized feature, mainly relevant in advanced scenarios where you need genuinely different settings across different worktrees of the same repository. Most everyday configuration needs are fully covered by the system, global, and local levels.

Summary

Git configuration operates across four levels of increasing specificity, each overriding the ones before it: system (every user, every repository on a machine), global (all repositories for the current user, in `~/.gitconfig`), local (one specific repository, in `.git/config`), and worktree (one specific worktree of a repository, the most narrowly scoped level, requiring an explicit opt-in via `git config extensions.worktreeConfig true` before Git recognizes it at all, relevant to Module 7's `git worktree` feature). The complete precedence order is `system < global < local < worktree`, with the most specific applicable level always winning for any given setting — directly extending Module 1's original three-level explanation. When a setting's actual value is unclear or unexpected given multiple potentially applicable levels, `git config --list --show-origin` provides the definitive diagnosis, listing every active setting precisely annotated with the exact file it came from.