How to Gitconfig

A practical Guide to managing multiple git Users

A figurine of an oktokat in the center, in the background a laptop with the main page of the GitHub open.

Photo by Roman Synkevych on Unsplash

When working with Git, having an organized and efficient configuration can make a world of difference. Over the past few days, I’ve been diving deep into my .gitconfig, tweaking it to suit both my personal and professional needs. In this article, I’ll walk you through the steps I took to set up a clean and flexible Git configuration, including managing multiple users, enabling GPG signing, and using a global .gitignore for a smoother development experience.

Whether you’re just starting with Git or looking to refine your setup, these tips will help you get the most out of your workflow.

Setting up your initial ~/.gitconfig

The first step to organizing your Git setup is creating a clean, fresh ~/.gitconfig file. Starting from scratch ensures that you’re working with a simple and minimal configuration before adding any customizations.

To do this, I used the following commands to set my global username and email address:

git config --global user.name "$USERNAME"
git config --global user.email "$USEREMAIL"

After running these commands, my initial ~/.gitconfig looked like this:

[user]
	name = $USERNAME
	email = $USEREMAIL

This basic configuration is sufficient for general Git usage, but it has limitations. For example, if you’re working on projects for both personal and professional purposes, you might need to use different usernames and email addresses depending on the context. A single global configuration won’t cover this scenario, so we’ll explore how to manage multiple Git user profiles in the next section.

Configuring Multiple Git Users

If you use Git for both personal and professional projects, you’ll likely need multiple user profiles, one for your personal GitHub account and another for your company account. Thankfully, Git allows us to manage multiple users by configuring specific profiles for different directories. Let’s walk through how to set this up.

Step 1: Create a Base Configuration

First, start with a global user configuration. This will act as the default user profile when no other specific configuration applies:

[user]
    name = $USERNAME
    email = $USEREMAIL

Step 2: Set Up Directory-Specific Configurations

Next, we’ll tell Git to use specific user configurations based on the directory you’re working in. For example, if you’re working on projects under ~/git/COMPANY1/, Git should use the user profile defined in a separate configuration file, ~/.gitconfig_company1. Similarly, for ~/git/COMPANY2/, another specific profile will be used.

Here’s how you can set this up in your ~/.gitconfig file

[user]
    name = $USERNAME
    email = $USEREMAIL
[includeIf "gitdir:~/git/COMPANY1/"]
    path = ~/.gitconfig_company1
[includeIf "gitdir:~/git/COMPANY2/"]
    path = ~/.gitconfig_company2
  • includeIf "gitdir:~/git/COMPANY1/": Tells Git to use the configuration file ~/.gitconfig_company1 for any repository located in the ~/git/COMPANY1/ directory.
  • includeIf "gitdir:~/git/COMPANY2/": Specifies that Git should use ~/.gitconfig_company2 for repositories under ~/git/COMPANY2/.

Step 3: Create User-Specific Configuration Files

Now, let’s create the configuration files for the company-specific users. For the first user (COMPANY1), run the following command to generate ~/.gitconfig_company1:

cat <<EOF > ~/.gitconfig_company1
[user]
    name = $COMPANY1_USERNAME
    email = $COMPANY1_USEREMAIL
EOF

Repeat the process for the second user (COMPANY2) by creating ~/.gitconfig_company2:

cat <<EOF > ~/.gitconfig_company2
[user]
	name = $COMPANY2_USERNAME
	email = $COMPANY2_USEREMAIL
EOF

Step 4: Verify the Configuration

At this point, you’ve successfully configured Git to use different user profiles based on the project directory. For example:

  • If you work in ~/git/COMPANY1/, Git will use the credentials from ~/.gitconfig_company1.
  • If you work in ~/git/COMPANY2/, Git will use the credentials from ~/.gitconfig_company2.

This setup ensures that commits and pushes in each directory are associated with the correct username and email address.

Setting Up a Global .gitignore

To simplify your Git workflow, it’s a good idea to set up a global .gitignore. This file allows you to define patterns for files or directories that Git should ignore across all your projects, saving you from having to create project-specific .gitignore files every time.

Step 1: Configure a Global .gitignore

You can create and configure a global .gitignore by running the following command:

git config --global core.excludesfile ~/.gitignore_global

This tells Git to reference the ~/.gitignore_global file whenever it checks for files to ignore. Once configured, your .gitconfig will include the following entry:

[core]
    excludesfile = ~/.gitignore_global

Step 2: Populate Your Global .gitignore

Next, add the patterns of files and directories you want Git to ignore to the ~/.gitignore_global file. Here’s an example of a typical .gitignore_global:

# Node.js
npm-debug.log

# macOS
.DS_Store

# Windows
Thumbs.db

# WebStorm
.idea/

# vi
*~

# General logs
log/
*.log

# Swap files
.*.swp

This configuration helps you avoid committing unnecessary files like editor-specific directories, operating system artifacts, and temporary files.

Step 3: Use Tools to Generate .gitignore Files

if you’re unsure of what to include in your .gitignore, tools like Toptal’s Gitignore Generator can help you quickly create tailored .gitignore files for different programming languages and frameworks. Simply select the technologies you’re using, and it will generate a comprehensive .gitignore for you, which you can then adapt for global or project-specific use.

By setting up a global .gitignore, you’ll streamline your workflow and ensure that unnecessary files don’t clutter your repositories. With tools like Toptal’s Gitignore Generator, creating efficient .gitignore files becomes even easier.

Automatically Signing Commits with Different Git Users

If you want to ensure the integrity of your commits, using GPG signing is a great practice. Here’s how to set up automatic commit signing for multiple Git users, step by step.

Step 1: Generate a GPG Key

To sign commits, you’ll first need a GPG key associated with your verified email address. Generate one using the following command:

gpg --full-generate-key

When prompted, choose a key length of 4096 bits for added security, and set an expiration date if you prefer. Remember, once the key expires, you’ll need to extend its validity or generate a new one.

Step 2: Find Your GPG Key ID

After generating your key, you can find its key ID by running:

gpg --list-secret-keys --keyid-format LONG

The output will look something like this:

sec   rsa4096/590E5507213AC509 2020-09-15 [SC]
      E163E5A1D0E6CAD4852F4FCA590E5507213AC509
uid                 [ultimate] testing (Key for Testing) <testing@git.com>
ssb   rsa4096/7AB123B711CBE904 2020-09-15 [E]

The key ID in this case is 590E5507213AC509. We’ll use this ID to configure Git.

Step 3: Add the Signing Key to Your Global Git Configuration

To enable GPG signing for your global Git user, run:

git config --global user.signingkey 590E5507213AC509

This sets the signing key for the global user profile.

Step 4: Configure Signing Keys for Multiple Users

If you have multiple Git user profiles (e.g., for work and personal projects), you’ll need to configure a signing key for each. For example, in the configuration file for your first company (~/.gitconfig_company1), you’d include:

[user]
    name = $COMPANY1_USERNAME
    email = $COMPANY1_USEREMAIL
    signingkey = 590E5507213AC509

Repeat this process for other user profiles (~/.gitconfig_company2, etc.), ensuring that each user has their own GPG key.

Tip: For maximum security, generate a unique GPG key for each email address instead of reusing the same key across multiple profiles.

Step 5: Finalize Your .gitconfig

After setting up your signing keys, you’ll need to update your global ~/.gitconfig to include the necessary GPG and credential settings. On macOS, for example, your configuration might look like this:

[user]
    signingkey = $KEY
    name = $USERNAME
    email = $USEREMAIL
[includeIf "gitdir:~/git/COMPANY1/"]
    path = ~/.gitconfig_company1
[includeIf "gitdir:~/git/COMPANY2/"]
    path = ~/.gitconfig_company2
[gpg]
    program = /usr/local/bin/gpg
[commit]
    gpsign = true
    gpgsign = true
[credential]
    helper = osxkeychain
[core]
    excludesfile = ~/.gitignore_global
  • [gpg] program: Specifies the path to the GPG program (in this case, /usr/local/bin/gpg on macOS).
  • [commit] gpgsign: Ensures that all commits are signed by default.
  • [credential] helper: Configures the credential helper for storing credentials securely.

With this setup, all your commits will be signed, ensuring their authenticity. Additionally, you’ve tailored the configuration to handle multiple Git users, with signing keys specific to each profile. This is particularly useful for managing both personal and professional repositories securely and efficiently.

Wrapping It Up

In this guide, we’ve built a robust Git configuration to streamline and enhance your workflow. Here’s what we’ve accomplished:

  • Multi-User Configuration: Set up a flexible .gitconfig to seamlessly manage multiple Git user profiles for personal and professional projects.
  • Global .gitignore: Created a global .gitignore file to exclude unnecessary files from being committed across all repositories.
  • GPG-Signed Commits: Enabled global commit signing to ensure the authenticity and integrity of your work.

With this setup, you’re now equipped to handle diverse Git scenarios efficiently, whether you’re contributing to a personal project or committing to a company repository.

You’re ready to work smarter with Git, happy coding!

Don’t Trust Me — Seriously

The author takes no responsibility for any mishaps, broken servers, or existential crises caused by following this information.

If you spot a mistake, have a better way of doing things, or just want to chat about tech, feel free to reach out.

Also, this isn’t an ad — unless my enthusiasm and advocacy for cool stuff count as advertising.