How to configure your Git repository with the git config command

The git config command is used for setting and querying various Git configuration options. These options control various aspects of Git's operation and look, including user information, editor preferences, repository-specific settings, and more.

This guide covers common use cases of the git config command.

Configuring username and email with git config

Before you start committing in Git, it's essential to set up your username and email address since every Git commit uses this information.

• Set Global Username and Email:

  git config --global user.name "Your Name" git config --global user.email "your_email@example.com"

  1. git config --global user.name "Your Name": sets the name that will be attached to your commits and tags as the author. "Your Name" should be replaced with your actual name or the name you wish to appear in your commits. The --global flag means this setting is applied across all Git repositories on your computer, for the current user. If you make a commit, Git records this name as the author of the commit.

  2. git config --global user.email "your_email@example.com": sets your email address for all your Git repositories on your computer. "your_email@example.com" should be replaced with your actual email address. This email is used in commits you make, and it's important for services like GitHub, GitLab, or Bitbucket to link your commits to your account on these platforms.

• Set username and email for a specific repository: You can also set these fields per repository. To do this, navigate to your repository directory and run:

  git config user.name "Your Name" git config user.email "your_email@example.com"

  Without the --global flag, git config only affects the local configuration of the repository you are currently in. This allows for repository-specific settings that override the global configurations for that specific repository.

Listing and showing configurations

• List all configurations:

  git config --list

  When you run the git config --list command in your console or terminal, Git will display all the configuration settings that are currently set for your Git installation, including local, global, and system configurations. Here's an example of what the output might look like:

user.name=Your Name
user.email=your_email@example.com
core.repositoryformatversion=0
core.filemode=true
core.bare=false
core.logallrefupdates=true
core.ignorecase=true
remote.origin.url=https://github.com/username/repository.git
remote.origin.fetch=+refs/heads/*:refs/remotes/origin/*
branch.main.remote=origin
branch.main.merge=refs/heads/main
commit.template=/path/to/commit_template.txt
merge.tool=vimdiff
diff.tool=vimdiff
core.editor=nano
alias.co=checkout
alias.br=branch
alias.ci=commit
alias.st=status
color.ui=true
color.status=auto
color.branch=auto
credential.helper=cache --timeout=3600

This output shows a mix of global and local settings:

• user.name and user.email are globally set user identification settings for commits.

• core.repositoryformatversion, core.filemode, core.bare, and others are internal settings for the repository.

• remote.origin.url and remote.origin.fetch specify the URL of the remote repository named "origin" and how branches are fetched from it.

• branch.main.remote and branch.main.merge configure the default upstream branch for the local main branch.

• commit.template points to a file that Git will use as the default message template for commits.

• merge.tool and diff.tool specify the tools to use for merging and diffing.

• core.editor defines the default text editor for Git operations that require one.

• alias entries show custom shortcuts for common Git commands.

• color.ui, color.status, and color.branch are preferences for colored output in Git commands.

• credential.helper configures Git to cache your password for a limited time.

While the exact output will vary based on your configuration settings, this command is useful for verifying current configurations or diagnosing unexpected Git behaviors.

• Show specific configuration: You can also check specific configurations by passing in a specific field as an argument to the git config command:

  git config user.name

  For example, this command will output the currently configured username.

Configuration levels

Git config works at three levels: local, global, and system.

Local Configuration (--local)

• Scope: Local configuration applies only to a specific repository. Each repository on your system can have a unique local configuration. Local configurations take precedence, and override global configurations.

• Use cases: Use local configurations for settings that should only apply to a specific project, such as project-specific user names, email addresses, merge strategies, or Git hooks.

• Location: These settings are stored in the .git/config file within the repository's directory.

• Example: This command sets Vim as the editor for this particular repository.

  git config --local core.editor vim

Global configuration (--global)

• Scope: Global configuration affects all the repositories used by the current user on the machine. It allows you to define settings that you want to apply across your projects.

• Use cases: Ideal for settings like your user name and email, which are likely to be consistent across all your Git activities. Also used for defining global ignore patterns and setting up aliases you want available in every project.

• Location: These settings are stored in a .gitconfig file located in the user's home directory (~/.gitconfig on Unix-like systems and C:\\\\Users\\\\USERNAME\\\\.gitconfig on Windows).

• Example: This sets your email address for all your repositories.

  git config --global user.email "your_email@example.com"

System configuration (--system)

• Scope: System configuration is applied across all users on the current computer. This level is typically used for settings that should be universal across all projects and users on the machine.

• Use cases: System-level configurations might include settings related to system-wide Git behavior, security configurations, or network settings. This is particularly useful in organizational contexts where many users operate on the same system.

• Location: The configuration file for system-level settings varies by operating system. On Unix-like systems, it's often located at /etc/gitconfig. On Windows, it might be found in C:\\\\ProgramData\\\\Git\\\\config.

• Command example: This example disables automatic conversion of line endings for every user on the system.

  sudo git config --system core.autocrlf false

Prioritization of configurations

Git prioritizes configurations at the local level over the global level, and global over system, meaning that if the same configuration is specified at multiple levels, the more specific level takes precedence. For example, a user.email setting in the local configuration of a repository will override the global configuration.

Best practices

1. Use local for project-specific settings: Customize behavior for individual projects without affecting your global setup.

2. Leverage global for personal defaults: Set your identity and preferences that you want to apply across all your projects.

3. Reserve system for universal settings: Administrators can set configurations that apply to all users, useful in managed or shared environments.

Understanding and utilizing these three levels of configuration allows for a highly customizable and efficient Git workflow, tailored to the needs of individual projects, users, and entire systems.

Editing config files directly

• To edit system configuration run:

  git config --system --edit

• To edit global configuration run:

  git config --global --edit

• To edit local configuration run:

  git config --edit

The default text editor for git config can be set using:

git config --global core.editor "editor_name"

Configuration file locations

• Global configuration file location:

  • Linux/Mac: ~/.gitconfig

  • Windows: C:\\\\Users\\\\USERNAME\\\\.gitconfig

• System configuration file location:

  • Linux/Mac: /etc/gitconfig

  • Windows: C:\\\\ProgramData\\\\Git\\\\config

• Local configuration file location: Inside the repository: .git/config

Tips for Effective Configuration

• Always ensure your user name and email are correctly set before starting to work in a new environment.

• Use the -global flag for settings that you want to apply across all your projects.

• Repository-specific settings (local) can override global settings. Use this feature to customize behavior per project.

• Regularly review your configuration using git config --list to ensure it matches your current setup and preferences.

For further reading on Git configuration, see the official Git documentation.