Configuration

Git needs configuration at different scopes because some choices belong to an entire computer, some to one user, and others to a particular repository or working tree. Understanding those scopes prevents a project-specific setting from accidentally affecting every repository.

1. The configuration layers

Git normally reads configuration from broad scopes first and more specific scopes afterward:

System → Global → Local → Worktree

When the same key exists at several scopes, the more specific applicable value overrides the broader one. It does not delete or rewrite the broader value.

Scope	Applies to	Typical source on Windows
system	Every user of this Git installation	C:/Program Files/Git/etc/gitconfig
global	The current operating-system user	C:/Users/<user>/.gitconfig
local	The current repository and its linked worktrees	.git/config
worktree	One worktree only	That worktree’s config.worktree file

Exact paths can vary. Ask Git for the source instead of relying only on a memorized path.

2. Precedence in practice

Suppose the global configuration contains:

user.email=personal@example.com

and a company repository has this local value:

user.email=work@company.com

Inside the company repository, Git uses work@company.com. Other repositories without a local override continue to use personal@example.com.

The narrower value wins only in its own scope. Removing it reveals the next applicable value underneath.

3. Local repositories and linked worktrees

A normal repository has one visible working tree. git worktree can attach additional working directories to the same repository, often with a different branch checked out in each directory:

backend-api/          → main
backend-api-feature/  → feature/payments

Those worktrees share repository history and local configuration, but each has its own files and HEAD. Worktree configuration allows one linked worktree to override a setting without changing its siblings.

Worktree-specific configuration must first be enabled for the repository:

git config extensions.worktreeConfig true
git config --worktree <key> <value>

Use this scope only when the setting genuinely belongs to one working tree.

4. Inspect values, scopes, and sources

List applicable entries with both their logical scope and physical source:

git config --list --show-scope --show-origin

The two options answer different questions:

• --show-scope: was the value read from system, global, local, worktree, or another supported scope?
• --show-origin: which file or other input supplied the value?

Example:

global  file:C:/Users/Yousef/.gitconfig  user.email=personal@example.com
local   file:.git/config                 user.email=work@company.com

To inspect the effective value of one key:

git config --get user.email
git config --get --show-scope --show-origin user.email

To inspect one scope explicitly:

git config --global --get user.email
git config --local --get user.email

If --get cannot find the key, it prints no value and normally exits with status 1. That is different from a key that exists with an empty value.

5. Write and remove values safely

Specify the intended scope when changing configuration:

git config --global user.email "personal@example.com"
git config --local user.email "work@company.com"
git config --local --unset user.email

The last command removes only the local value. The global value remains and becomes effective again.

Inside a repository, writing without an explicit scope defaults to local:

git config user.name "Yousef"

Outside a repository, that command normally fails because no local configuration file is available. Writing the scope explicitly makes the command’s effect easier to review.

6. Practical inspection

A disposable repository can be used to verify the model safely:

git init config-lab
cd config-lab
git config --local course.environment "training"
git config --get --show-scope --show-origin course.environment

Expected shape:

local  file:.git/config  training

Then remove and verify the key:

git config --local --unset course.environment
git config --local --get course.environment
echo $?

In Git Bash, exit status 1 confirms that the key was not found.

7. Common mistakes

• Assuming --show-origin refers to the remote named origin.
• Treating system, global, and local as separate unrelated settings instead of layered inputs.
• Assuming an override deleted the broader value.
• Writing without checking the current repository or intended scope.
• Interpreting no output as a stored empty value without checking exit status.
• Using worktree configuration when a repository-wide local setting is enough.

8. Summary

System → Global → Local → Worktree
more specific applicable value = higher precedence
--show-scope  = logical configuration level
--show-origin = exact file or input source
--get         = read a value
--unset       = remove it from the selected scope

9. Knowledge check

1. A key exists globally and locally. Which value is effective?

The local value, because it is more specific to the current repository. The global value still exists and remains available to other repositories.

2. What is the difference between –show-scope and –show-origin?

The scope identifies the configuration level. The origin identifies the exact file or other input from which Git read the value.

3. What happens after a local override is unset?

Git uses the next applicable value, such as the global or system value. Unsetting the local key does not delete those broader values.

4. Why can a failed –get command produce no output?

The key may not exist. An exit status of 1 distinguishes that case from a successful lookup.