Git-Config: Configuration Scopes
Configure Git Differently for Individual Repositories
In this post, we’re going to look at three basic levels of scope you can work at to configure Git. If you’ve been following along with the posts in this series, you might have seen a setting that seemed useful to you—but only on certain projects. Understanding Git’s basic levels of configuration scope is the first step to adjusting Git’s behavior to suit your preferences on specific projects.
Explore Scope Levels
Go ahead and see what levels of scope you’re working with. Change into one of your projects that you keep under Git control and run git config --list --show-scope. Depending on your operating system and the global configuration values you’ve set, you’ll see something similar to this:
If you’re running an older version of Git, you’ll probably see error: unknown option 'show-scope'. In that case, run git config --list --show-origin, which will instead tell you the file locations for each set of configuration scopes you're running. Based on those locations, you should be able to determine system, global, and local levels of configuration scope.
System-Level Scope
The system-level scope is set as part of Git’s installation on your system. You might not find any system-level settings at all. Installations of Git on macOS via Homebrew, for example, will report a single setting of credential.helper=osxkeychain.
If your user account has sudo privileges, you can edit the system-level file as reported with the --show-origin option. But editing that file is probably not a good idea. However, if you’re working on a system where there is, for example, a typo in the system-level configuration file that is causing you headaches—and you don’t have the privileges to fix the file—you can set the variable GIT_CONFIG_NOSYSTEM in your shell’s startup scripts, which will disable the system-level file.
Global Scope
The global scope is your configuration as you work across different Git repositories from within a single login. This is the level of scope you should write to when you have a Git preference you want in place for the majority of your projects. (We’ll look at deviating from global preferences in the next section, on per-repo levels of scope.) From the command line, you write to your global configuration file by including the --global option in your calls to git config.
Older Git installations keep your global configuration in a file like ~/.gitconfig. Newer installations, however, can access a config file inside ~/.config/git.
Local, Per-Repo Scope
At the lowest level of scope, each Git repository has a config file inside the .git/ directory. You’ll find a handful of values automatically set for you in .git/config, depending on how and when you initialized or cloned the repository.
You can override your global configuration settings on a per-repo basis. Run the same git config command you normally would, but just leave off the --global option.
For example, if your global Git configuration has your user.name as Darth Vader but you’re low-key trying to leave the Dark Side outside of regular working hours, you can set your user name for a specific repo like this:
$ cd ~/destroy-the-emperor/
$ git config user.name "Anakin Skywalker"Across your login, you’ll be Darth Vader, but in the destroy-the-emperor project, Git will know you as Anakin Skywalker.
Per-Repo Configuration Not Shared at Push
One important thing to know about per-repo configuration in .git/config is that that file is not shared when you push to a remote. On the one hand, that’s good for secret configuration values: you probably don’t, for example, want the whole world to know secret URIs where your project is deployed. But on the other hand, that does mean that you’ll have to find an out-of-band mechanism for sharing a per-repo configuration file—even with yourself, if you work across different machines. Because Git configuration files are merely plain-text files, you have plenty of options for sharing them over email, protected cloud storage, or even a private repo just for maintaining your configuration values.
That’s it: three levels of scope for configuring Git. It’s fairly rare to make use of the system level file. But you’ll write most of your preferences globally, and deviate from or add to those on a local, per-repo level of scope.
In the next post, we’ll look at configuring Git’s core.editor variable so you can run Git commands like git config --global --edit and work on Git’s configuration files in your text editor of choice — without your having to know where the files are located. Setting a core.editor value will also make it much easier for you to write and edit information-rich commit messages with git commit.
Karl’s book, Programming WebRTC: Build Real-Time Streaming Applications for the Web, is available in beta from The Pragmatic Bookshelf. You can save 35 percent with promo code git_config_2022 now through September 15, 2022. Promo codes are not valid on prior purchases.
