The Ultimate Guide to Git Config: Fine-Tuning Your Git Experience

But with dozens of options, where do you even start? Don't worry — we've got you covered.

In this comprehensive guide, we'll explore the ins and outs of git config, from the foundational settings to the "hidden gems" that will make you a Git power user.

Ready to customize your Git experience? Let's get started!

1. The What, Where, and How of Git Config

Before we dive into the cool stuff, let's get the basics right. Understanding how git config works is the foundation for everything else.

What is git config?

At its heart, git config is the command that lets you get and set configuration variables that control all aspects of Git's appearance and operation. These configurations can be as simple as setting your username or as complex as rewriting Git's core behaviors for diffing and merging.

The Three Levels of Configuration

Git provides three levels of configuration, each overriding the previous one:

1. System (--system): These settings apply to every user on the entire machine. You'll rarely need to touch this. The file is typically located at /etc/gitconfig.
2. Global (--global): This is where you'll set your personal preferences. These settings apply to all of your repositories. The file is located in your user's home directory (~/.gitconfig on Linux/macOS, C:\Users\<YourName>\.gitconfig on Windows). This is where the magic happens for most users!
3. Local (--local): These settings are specific to the repository you are currently in. They are stored in the .git/config file inside your repository and are perfect for project-specific overrides.

This layered system gives you incredible flexibility. You can set a global preference and then override it for a specific project that has different needs.

Basic Commands

Interacting with these settings is straightforward. Here are the commands you'll use most often:

# View all settings (from all levels)
git config --list

# View a specific setting
git config user.name

# Set a global setting
git config --global user.name "Your Name"

# Set a local setting for the current repository
git config --local user.email "your-email@example.com"

# Remove a setting
git config --global --unset user.signingkey

The Config File Syntax

While using git config --set is great, sometimes it's easier to open the .gitconfig file with your favorite text editor and edit it directly.

The syntax is simple and intuitive:

[section]
    key = value

# This is a comment
; This is also a comment

[alias]
    co = checkout
    st = status

[user]
    name = Bruno Brito
    email = bruno@git-tower.com

Sections are denoted by square brackets (e.g., [user]), followed by key-value pairs.

Modularizing Your Config with include

As your .gitconfig file grows, it can become a bit unwieldy. A fantastic feature for staying organized is include.path. It allows you to split your configuration into multiple files.

For example, you could keep all your Git aliases in a separate ~/.gitconfig-aliases file:

# In ~/.gitconfig
[include]
    path = ~/.gitconfig-aliases

Then, in ~/.gitconfig-aliases:

[alias]
    co = checkout
    st = status
    br = branch
    lg = log --oneline --graph --decorate

This keeps your main config file clean and makes your settings easier to manage or even share!

2. The Essentials: Your Identity and Core Settings

In this section, we will cover the essential settings that every developer should configure.

• Setting Your Identity: This is the first thing you should do on a new machine. It ensures all your work is properly attributed to you.

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

• Choosing Your Default Branch Name: The default branch name in new repositories used to be master. The community has since shifted towards main. You can make main your default for all new projects:

  git config --global init.defaultBranch main

• The Core Editor: When Git needs you to enter a message (like for a commit or a merge), it opens an editor. You should tell Git which one to use:

  # For VS Code
  git config --global core.editor "code --wait"

• Handling Line Endings: To prevent issues when collaborating with people on different operating systems (Windows vs. Mac/Linux), it's a good practice to configure how Git handles line endings.

  # For macOS/Linux
  git config --global core.autocrlf input
  # For Windows
  git config --global core.autocrlf true

• Ignoring File Permissions: Have you ever seen a file show up as "modified" when you only changed its executable permissions? This can be annoying. If you don't need to track file permissions, you can tell Git to ignore these changes:

  git config --global core.fileMode false

3. Productivity Boosters for Smoother Workflows

With the basics out of the way, let's look at some settings that will save you time and make Git more enjoyable to use.

Aliases: Your Personal Git Shortcuts

Aliases are one of the most powerful features in git config. They let you create your own shortcuts for longer commands.

[alias]
    # Simple shortcuts
    co = checkout
    st = status
    br = branch

    # A more complex log format
    lg = log --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit

    # Run a shell command!
    purge = "!git branch --merged | egrep -v '(^\\*|main|develop)' | xargs git branch -d"

With the lg alias above, git lg gives you a beautifully formatted history. The purge alias lets you clean up all your merged local branches with a single command!

Controlling Your Git Output Color Palette

Since version 1.8.4, Git's output has become colorful, making it easier to read at a glance. However, if you prefer a more monochromatic appearance, you can adjust the settings by typing the following:

git config --global color.ui false

This single command disables color for Git's output (like diff, status, and branch) when you're using a terminal.

The Pager

Sometimes, a command's output is too long to fit on your screen (like git log). Git uses a "pager" (like less) to let you scroll through it but you can control this behavior.

For example, to disable the pager for git branch:

git config --global pager.branch false

With this setting, all branches will print directly to the terminal.

Rebase by Default

If you prefer a clean, linear history, you might favor git pull --rebase over a merge commit every time you pull. You can make this the default:

git config --global pull.rebase true

This is a game-changer for many developers who love a tidy commit history.

4. More Powerful Features and Hidden Gems

Now for the really fun stuff! These are some of the lesser-known settings that can solve common frustrations and make you look like a Git wizard.

• --force-with-lease: The Safer Force Push. You probably already know git push --force is dangerous. A safer alternative is --force-with-lease, which will fail if someone else has pushed to the branch in the meantime. Make it an easy-to-use alias:

  [alias]
    pf = push --force-with-lease

• Better Diffs: You can tell Git to use a different algorithm for calculating diffs, which can sometimes produce more readable results.

  git config --global diff.algorithm patience

  These are the available algorithms:

  • myers: The default algorithm (fast, but may produce confusing diffs).
  • patience: Slower, but often more human-readable.
  • minimal: Aims to generate the smallest possible diff.
  • histogram: An improvement over patience (faster, with similar quality).

• blame.ignoreRevsFile: Ignoring Formatting Commits: Ever run git blame only to find that a massive reformatting commit is "blamed" for every line? As explained in more detail here, you can tell Git to ignore these commits! Create a file named .git-blame-ignore-revs with the commit hashes to ignore, and then run:

  git config blame.ignoreRevsFile .git-blame-ignore-revs

• help.autocorrect: For the Typo-Prone Developer: Do you ever type git chekcout? Git can automatically correct your typos and run the right command for you. In the example below, the value of 10 represents 10 deciseconds, which is equivalent to 1 second.

  # Waits 1 second (10 deciseconds) before running the corrected command
  git config --global help.autocorrect 10

• rerere: Reuse Recorded Resolution: If you find yourself resolving the same merge conflicts over and over (especially in long-lived feature branches), rerere is your new best friend. It stands for "Reuse Recorded Resolution" and you can learn more about it in this blog post.

  git config --global rerere.enabled true

  Once enabled, Git will remember how you resolved a conflict. The next time it sees the exact same conflict, it will resolve it for you automatically!

5. Performance Tuning for Large Repositories

Working in a massive monorepo? Does git status take forever? These performance-oriented settings, many of which are covered in our detailed guide to Git performance, can make a world of difference.

• The Commit Graph: This feature dramatically speeds up history-traversing operations like git log.

  git config --global core.commitGraph true
  git config --global gc.writeCommitGraph true
  git config --global fetch.writeCommitGraph true

• Filesystem Monitor (fsmonitor): This is perhaps the biggest performance booster for large repos. It uses a background process to watch for file changes, making commands like git status nearly instantaneous.

  git config --global core.fsmonitor true

• The Untracked Cache: Works with fsmonitor to speed up how Git finds new, untracked files.

  git config --global core.untrackedCache true

For more tips on repository performance, you should really consider reading our in-depth article on the topic.

6. Security and Best Practices

Finally, let's look at some settings that enhance security and help you manage different contexts.

• Signing Your Commits: You can sign your commits with a GPG key or SSH to verify your identity. This is great for open-source work and corporate environments.

  git config --global user.signingkey <YourGPGKeyID>
  git config --global commit.gpgSign true

• Conditional Includes: This is one of the most powerful "hidden gems". includeIf lets you use different configurations based on the repository's path. This is perfect for managing work and personal projects.

For example, you can use your work email for all repositories inside ~/work/:

# In ~/.gitconfig
[user]
    name = Bruno Brito (Personal)
    email = bruno.personal@gmail.com

[includeIf "gitdir:~/work/"]
    path = ~/.gitconfig-work

Then, in ~/.gitconfig-work:

[user]
    name = Bruno Brito (Tower)
    email = bruno@git-tower.com

Now, Git will automatically use the correct name and email depending on where your repository is located!

A Recommended .gitconfig Template

Feeling inspired? Here’s a template you can use as a starting point for your own awesome .gitconfig:

[user]
    name = Your Name
    email = you@example.com

[init]
    defaultBranch = main

[core]
    editor = code --wait
    autocrlf = input
    fileMode = false
    fsmonitor = true
    untrackedCache = true

[color]
    ui = auto

[pull]
    rebase = true

[rerere]
    enabled = true

[help]
    autocorrect = 10

[alias]
    co = checkout
    ci = commit
    st = status
    br = branch
    lg = log --graph --abbrev-commit --decorate --format=format:'%C(bold blue)%h%C(reset) - %C(bold green)(%ar)%C(reset) %C(white)%s%C(reset) %C(dim white)- %an%C(reset)%C(bold yellow)%d%C(reset)' --all
    pf = push --force-with-lease

# Use work email for repos in the ~/work/ directory
[includeIf "gitdir:~/work/"]
    path = ~/.gitconfig-work

Final Words

And there you have it! From simple aliases to powerful performance tuning, you're now equipped to create a Git configuration that works for you, not against you.

Don't be afraid to experiment and find the settings that best fit your workflow. A well-crafted .gitconfig is a sign of a true Git artisan! 😎

For more tips, don't forget to sign up for our newsletter below and follow Tower on Twitter and LinkedIn!