Set git config Values Without Losing Track of Scope

You ran git config once, a setting went somewhere you did not expect, and now commits carry the wrong email. This guide fixes that in about fifteen minutes: set options in the right place, see which file supplies each value, and undo what you did. The examples use Git 2.43.0 (installed here from the git-man package), you need a shell and a repository for the local examples, and nothing below needs sudo.

Git reads its configuration in layers. System settings come first, then global files such as ~/.gitconfig and $XDG_CONFIG_HOME/git/config, then the repository's .git/config. A later value normally wins.

The catch: a write goes to the repository file by default. That is the detail that surprises people.

1. Check the installed command

Confirm the version and read the local synopsis before you copy an option from an article written for another release:

$ git --version
git version 2.43.0
$ git config --help

The second command may open a pager or a browser. Configuration syntax and options change between releases, so the installed manual is the authority for the machine you are on, not a newer web page.

2. Set a repository-only identity

Use --local when an identity belongs to one repository, such as a work project or a separate personal address. It writes .git/config and leaves your global defaults alone:

$ cd /path/to/repository
$ git config --local user.name 'Your Name'
$ git config --local user.email '[email protected]'
$ git config --local --get-regexp '^user\.(name|email)$'
user.name Your Name
user.email [email protected]

• Pick a publishable address. It ends up in commit metadata for good.
• It is not a credential. This setting does not authenticate you and does not change your hosting account.
• Not in a work tree? Check where you are with git rev-parse --show-toplevel rather than adding sudo.

To undo these two writes, remove only the keys you set:

$ git config --local --unset user.name
$ git config --local --unset user.email

3. Choose global scope deliberately

Use --global for a preference that should apply across all your repositories. For example, this enables coloured Git output where Git decides it is appropriate:

$ git config --global color.ui auto
$ git config --global --get color.ui
auto

This edits a file in your home directory. It is an ordinary user operation, not an administrative one, but it affects future Git commands outside the current repository. Remove it to return to Git's normal fallback behaviour:

$ git config --global --unset color.ui

4. Inspect the winning value and its origin

A plain lookup hides the layer that supplied a value. Ask Git to show the scope and the source file:

$ git config --show-scope --show-origin --get user.email
local  file:.git/config  [email protected]

Your path and value will differ. In a repository, local means .git/config and global means one of the user configuration files. If several layers define a key, list them all with their origins:

$ git config --show-scope --show-origin --get-all user.email
global file:/home/you/.gitconfig [email protected]
local  file:.git/config [email protected]

For a single-valued option the last value usually wins, while multi-valued options keep every entry. This is the quickest way to spot a surprise system or global setting, and it edits nothing.

For a broad audit, list the whole configuration with the same provenance columns:

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

5. Read values in the type Git expects

Use --type when a script or check needs canonical output. Git accepts several boolean spellings but reports one canonical boolean:

$ git config --local core.filemode
true
$ git config --local --type=bool core.filemode
true

• The type must match the option. core.autocrlf accepts true, false and input, so reading it as a boolean is an error.
• Integers can be read with --type=int.
• Paths can be expanded for reading with --type=path.
• A failed type check is a signal. It tells you the stored value is unsuitable for what you are about to do.

When a missing key is an expected case, give it a default instead of turning a normal lookup into an error:

$ git config --local --default '(not set)' --get user.signingkey
(not set)

6. Treat repeated keys as a list

Some options legitimately occur more than once. Use --add to append an entry and --get-all to inspect every entry:

$ git config --local --add remote.origin.fetch '+refs/tags/*:refs/tags/*'
$ git config --local --get-all remote.origin.fetch
+refs/heads/*:refs/remotes/origin/*
+refs/tags/*:refs/tags/*

Do not use a plain git config name value when you mean to append, because its normal write replaces at most one matching line. To remove exactly the entry added above, use a fixed-value match:

$ git config --local --fixed-value --unset remote.origin.fetch '+refs/tags/*:refs/tags/*'

7. Diagnose failures without guessing

Git returns status 0 on success. Invalid names, malformed configuration, unwritable files and missing keys for an unset operation all give non-zero statuses. Capture the status straight away when you are testing a script:

$ git config --local --get does.not.exist
$ printf 'exit status: %s\n' "$?"
exit status: 1

If Git reports an invalid configuration file, stop and inspect the named file before you make more changes.

If a setting seems to be ignored, repeat the lookup with --show-origin and --show-scope, then check for:

• An included file that overrides it.
• A more specific repository setting that beats the global one.
• A one-command override such as git -c name=value ....