Setting up Git properly: real-world lessons and examples

Setting up Git properly: real-world lessons and examples. Configuration you should do once.

Why Git configuration matters on day one

Most developers rush through Git setup, treating configuration as a checkbox to tick before the real work begins. We've seen teams where commits carry wrong names, pull workflows cause merge headaches, and authentication becomes a daily pain point. Setting up Git properly on day one saves you hundreds of hours across your career—and it only takes a few minutes.

In this guide, we'll walk through the configuration you should do once and why it matters. These aren't advanced tricks; they're the fundamentals that separate a smooth development experience from constant friction. Setting up Git properly means your commits tell the right story, your pulls behave predictably, and authentication never slows you down.

Identity: name and email for every commit

Every commit you make carries metadata: a timestamp, a message, and your identity. That identity is your name and email address. In production teams, this matters more than it might seem. Blame archaeology, security audits, and code reviews all trace back to this data. A teammate should know exactly who wrote a piece of code without guessing or hunting through Slack.

Configure your identity globally so it applies to all repositories on your machine:

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

Use your real name, not a nickname or acronym. Future you, your team, and your organization's auditors will thank you. If you work on multiple projects with different email addresses—say, a personal GitHub account and a corporate account—you can override at the repository level:

cd /path/to/work/repo
git config user.email work@company.com

Verify your setup with:

git config --global user.name
git config --global user.email

We've debugged more than one production incident where commits were tagged with "localhost" or "root" because someone skipped this step. Don't be that team. Set it once, set it right.

Default branch: aligning with modern naming conventions

For years, Git defaulted new repositories to master as the primary branch. Most modern teams now use main, and GitHub switched its default in 2020. If you don't configure this globally, you'll create new repositories with master while your team works on main—a small inconsistency that compounds across projects.

Set the default branch name once:

git config --global init.defaultBranch main

This applies whenever you run git init on a new local repository. Existing repositories are unaffected. If you join a team that uses a different convention—we've seen some use develop or trunk—you can adjust locally or document the override for team onboarding.

Why does this matter? Consistency reduces cognitive load. When every project uses the same primary branch name, you don't mentally stumble or mistype. In CI/CD pipelines, you avoid logic errors from branch-name mismatches. In production, it ensures new team members don't accidentally push feature work to the wrong place.

Better defaults: pull.rebase and rerere.enabled

Out of the box, git pull fetches and merges. This creates merge commits even for simple pulls, cluttering your history. For most teams, rebasing is cleaner and more predictable.

Enable rebase-first pulls:

git config --global pull.rebase true

Now git pull rebases your local commits on top of the remote branch rather than creating a merge commit. Your history stays linear and readable. If you ever need the old behavior, you can use git merge --no-rebase explicitly.

The second quality-of-life improvement is rerere—"reuse recorded resolution." When you resolve a merge conflict, Git can remember that resolution and apply it automatically if the same conflict happens again:

git config --global rerere.enabled true

In real projects, this is a lifesaver. Imagine rebasing a long-lived feature branch on top of main multiple times. The same conflicts resurface each time. With rerere enabled, Git learns your resolution the first time and applies it automatically on subsequent rebases. We've seen this save teams 5–10 minutes per rebase on large codebases.

Combine these two:

git config --global pull.rebase true
git config --global rerere.enabled true

After your first conflict resolution with rerere enabled, Git records it in .git/rr-cache. Future similar conflicts are handled without interruption. Your workflow becomes faster and your history cleaner.

Authentication: SSH or credential manager

Every time you push or pull from a remote repository over HTTPS, Git needs to verify you're authorized. The naive approach—typing a username and password—is tedious and insecure. Production teams use one of two approaches: SSH keys or a credential manager.

SSH authentication

SSH is the gold standard for Git authentication. You generate a keypair on your machine, add the public key to GitHub (or your Git host), and SSH handles authentication transparently. No passwords typed, no credentials in environment variables.

Generate an SSH key if you don't have one:

ssh-keygen -t ed25519 -C "you@example.com"

Press Enter to accept the default location (~/.ssh/id_ed25519), then optionally add a passphrase. Add the public key to GitHub via Settings > SSH and GPG keys. Verify the connection:

ssh -T git@github.com

You should see: Hi username! You've successfully authenticated, but GitHub does not provide shell access.

Then configure Git to use SSH for GitHub:

git config --global url."git@github.com:".insteadOf "https://github.com/"

Now all HTTPS URLs to GitHub automatically use SSH. Clone, push, and pull work without typing anything. This scales to your entire team and integrates seamlessly with CI/CD pipelines.

Credential manager

If SSH feels unfamiliar or your environment doesn't support it easily, a credential manager stores your credentials securely and supplies them automatically. Git Credential Manager (available on Windows, macOS, and Linux) is the modern standard:

git config --global credential.helper manager-core

On first push or pull, your system browser opens and you authenticate (e.g., via GitHub's OAuth flow). Your credentials are stored securely in your OS keychain. Subsequent operations use the stored credentials without prompting. It's less elegant than SSH, but it works reliably and requires less setup.

For teams using GitHub, we recommend SSH for developers and a credential manager for CI/CD systems. For organizations with corporate Git hosts or complex authentication, your IT team likely has a standard—follow it.

Verify your configuration

After making changes, check your global config file:

git config --global --list

Or view the file directly:

cat ~/.gitconfig

You should see entries like:

[user]
    name = Your Name
    email = you@example.com
[init]
    defaultBranch = main
[pull]
    rebase = true
[rerere]
    enabled = true
[credential]
    helper = manager-core

Common mistakes

• Using a generic or system name: Avoid names like "Developer" or "root." Future audits and blame archaeology depend on real identities. Use your actual name.
• Forgetting to configure at the repository level: If you work on multiple accounts, set identity globally once, then override locally where needed. Don't repeat work.
• Mixing SSH and HTTPS: Pick one approach and stick with it. Mixing them across repositories causes inconsistency and confusion. If you use SSH, convert all HTTPS remotes to SSH or use the insteadOf trick.
• Ignoring pull.rebase: Many teams default to this, then inherit it as muscle memory. Understand what it does before enabling it; don't blindly follow recommendations.
• Assuming rerere works for all conflicts: Rerere handles straightforward conflicts well. Complex or logic-heavy conflicts still require manual review. It's a helper, not a substitute for thinking.
• Storing passwords in environment variables: Never export GIT_AUTHOR_EMAIL or similar as plain text. Use a credential manager or SSH instead.

Key takeaways

• Set your identity once globally: name and email. Use your real name so commits are attributable and auditable.
• Set the default branch to main so new repositories align with modern conventions and team standards.
• Enable pull.rebase true for cleaner, linear history and fewer merge commits.
• Enable rerere.enabled true to automatically re-apply conflict resolutions, saving time on repeated rebases.
• Use SSH keys for authentication when possible; they're secure, password-free, and scale well. Fall back to a credential manager if SSH isn't available.
• Verify your configuration with git config --global --list to catch mistakes early.
• Document any team-specific overrides and include them in your onboarding checklist so new developers don't repeat common mistakes.