Installing and Configuring Git: Complete Guide for Windows, macOS, and Linux

Hands-on tutorial for installing Git on Windows, macOS, and Linux with initial configuration steps, verification, and troubleshooting.

published: March 31, 2026 reading time: 13 min read updated: March 31, 2026

Introduction

Git is the industry-standard version control system, and installing it correctly is the first step toward professional software development. While the installation process is straightforward on most platforms, there are important choices that affect your daily workflow — from terminal integration to credential handling and line ending normalization.

This guide walks you through installing Git on Windows, macOS, and Linux, followed by the essential configuration steps that every developer should complete before their first commit. Whether you are setting up a fresh machine or troubleshooting a problematic installation, this tutorial covers everything you need.

By the end, you will have a fully functional Git installation with proper identity settings, sensible defaults, and a verified setup ready for development. For deeper configuration options, see Git Config and Global Settings.

When to Use / When Not to Use

Install Git when:

Starting any software development project
Setting up a new development machine
Contributing to open source projects
Managing configuration files, scripts, or documentation
Preparing a CI/CD runner or build server
Learning version control fundamentals

Skip or delay installation when:

Your organization mandates a different VCS (SVN, Perforce) — install that instead
You only need to download code without contributing — use git clone via a portable Git or GitHub CLI
You are on a restricted system where you cannot install software — use GitHub Codespaces or GitPod

Core Concepts

Git installation involves three layers: the binary, the shell integration, and the configuration.

The binary is the git executable itself — a compiled program that implements all Git operations. It can be installed via package managers, standalone installers, or built from source.

Shell integration adds Git awareness to your terminal: command completion, branch name display in your prompt, and colored output. This is optional but highly recommended for productivity.

Configuration sets your identity, default editor, line ending behavior, and credential handling. Without proper configuration, Git will prompt you for your name and email on every commit, and may produce cross-platform compatibility issues.


graph TD
    A[Install Git Binary] --> B[Verify Installation]
    B --> C[Configure Identity]
    C --> D[Set Defaults]
    D --> E[Verify Configuration]
    E --> F[Ready for Development]

    subgraph "Installation Layers"
        A
        B
    end

    subgraph "Configuration"
        C
        D
        E
    end

Architecture or Flow Diagram

Git Installation Paths by Platform


graph LR
    subgraph "Windows"
        W1[Git for Windows Installer] --> W2[Git Bash + Git CMD]
        W1 --> W3[WSL Git]
    end

    subgraph "macOS"
        M1[Xcode Command Line Tools] --> M2[System Git]
        M3[Homebrew] --> M4[Homebrew Git]
    end

    subgraph "Linux"
        L1[apt/yum/pacman] --> L2[Package Manager Git]
        L3[Build from Source] --> L4[Latest Git]
    end

    W2 --> V[git --version]
    W3 --> V
    M2 --> V
    M4 --> V
    L2 --> V
    L4 --> V

Step-by-Step Guide / Deep Dive

Installing Git on Windows

Windows offers two primary approaches: the official Git for Windows installer, and Git within WSL (Windows Subsystem for Linux).

Option 1: Git for Windows (Recommended for most users)

Download the installer from git-scm.com/download/win
Run the installer. The default settings work well for most users, but pay attention to these key choices:
- Select Components: Check “Git Bash Here” and “Git GUI Here” for context menu integration
- Choosing the default editor: Select VS Code, Notepad++, or your preferred editor. Avoid Notepad — it does not handle Unix line endings well
- Adjusting your PATH environment: Choose “Git from the command line and also from 3rd-party software” to make git available in CMD, PowerShell, and VS Code terminal
- Configuring the line ending conversions: Choose “Checkout Windows-style, commit Unix-style line endings” — this is the safest cross-platform option
- Choosing the terminal emulator: Select “Use Windows’ default console window” unless you specifically want MinTTY
- Default behavior for git pull: Choose “Fast-forward or merge” for flexibility
- Credential helper: Choose “Git Credential Manager” for secure password storage
Complete the installation and open Git Bash or PowerShell to verify:


git --version

Option 2: Git in WSL

If you use WSL for development, install Git inside your Linux distribution:


# For Ubuntu/Debian
sudo apt update
sudo apt install git

# For Fedora
sudo dnf install git

# For Arch Linux
sudo pacman -S git

# Verify
git --version

Note: WSL Git and Windows Git are separate installations. Files modified in WSL should be committed using WSL Git to avoid line ending issues.

Installing Git on macOS

Option 1: Xcode Command Line Tools (Simplest)


xcode-select --install

A dialog will prompt you to install the tools. This includes Git along with other development utilities. Verify with:


git --version

Option 2: Homebrew (Recommended for latest version)

Homebrew provides more up-to-date Git versions than Xcode’s bundled copy:


# Install Homebrew if you do not have it
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Git
brew install git

# Verify
git --version

# Optionally, ensure Homebrew Git takes precedence over system Git
echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Installing Git on Linux

Ubuntu/Debian


sudo apt update
sudo apt install git
git --version

Fedora/RHEL/CentOS


sudo dnf install git
# Or for older systems:
# sudo yum install git
git --version

Arch Linux


sudo pacman -S git
git --version

Building from Source (Latest Version)

When your package manager’s Git is outdated:


# Install build dependencies
sudo apt install libz-dev libssl-dev libcurl4-gnutls-dev libexpat1-dev gettext cmake gcc

# Download the latest source
cd /tmp
curl -L https://github.com/git/git/archive/refs/heads/master.tar.gz -o git.tar.gz
tar -zxf git.tar.gz
cd git-master

# Build and install
make configure
./configure --prefix=/usr
make all
sudo make install

git --version

Initial Configuration

After installation, configure your identity and essential settings. These settings are stored in ~/.gitconfig (or %USERPROFILE%\.gitconfig on Windows).


# Set your identity (required for commits)
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

# Set your default editor
git config --global core.editor "code --wait"
# Alternatives:
# git config --global core.editor "vim"
# git config --global core.editor "nano"

# Set the default branch name
git config --global init.defaultBranch main

# Enable colored output
git config --global color.ui auto

# Set your preferred merge tool
git config --global merge.tool vscode
git config --global mergetool.vscode.cmd "code --wait $MERGED"

# Verify all settings
git config --global --list

Verifying Your Installation

Run this checklist to confirm everything works:


# 1. Check Git version
git --version

# 2. Verify identity is set
git config --global user.name
git config --global user.email

# 3. Test a local repository
cd /tmp
mkdir git-test && cd git-test
git init
echo "test" > test.txt
git add test.txt
git commit -m "Test commit"
git log --oneline

# 4. Clean up
cd /
rm -rf /tmp/git-test

Production Failure Scenarios + Mitigations

Scenario	Impact	Mitigation
Git not found in PATH after installation	Cannot run any Git commands	Restart terminal; verify PATH includes Git binary directory; reinstall with correct PATH option
Wrong Git version on macOS (Apple’s bundled old version)	Missing features, incompatibility with modern workflows	Install via Homebrew and ensure `/opt/homebrew/bin` precedes `/usr/bin` in PATH
Line ending mismatches between Windows and Linux developers	Spurious diffs, merge conflicts, CI failures	Set `core.autocrlf` appropriately; use `.gitattributes` with `* text=auto`
Credential helper not configured	Repeated password prompts, authentication failures	Install Git Credential Manager on Windows; use `git config --global credential.helper store` or keychain on macOS
SSH keys not configured	Cannot push/pull to SSH remotes	Generate SSH key with `ssh-keygen`, add public key to GitHub/GitLab, test with `ssh -T git@github.com`
Corrupted Git installation	Random errors, segfaults	Reinstall from official source; clear `~/.gitconfig` and reinstall
PATH conflicts with multiple Git versions on CI runners	Unpredictable behavior, different Git versions executing	Pin Git version in CI config; use `which git` and `git --version` in pipeline startup; remove duplicate installations

Trade-offs

Factor	Package Manager Install	Official Installer	Build from Source
Ease of setup	One command	GUI wizard	Multiple steps
Version freshness	Depends on repo	Current stable	Latest (bleeding edge)
Platform integration	Minimal	Full (context menus, credential manager)	None
Updates	Via package manager	Manual re-download	Manual rebuild
Customization	Limited	Installer options	Full control
Best for	Linux, macOS power users	Windows users, beginners	Developers needing latest features

Implementation Snippets

Windows: Git Bash Profile Customization


# Add to ~/.bashrc in Git Bash
# Show Git branch in prompt
parse_git_branch() {
    git branch 2>/dev/null | sed -n 's/^\* \(.*\)/ (\1)/p'
}
export PS1='\[\033[32m\]\u@\h\[\033[00m\]:\[\033[36m\]\w\[\033[33m\]$(parse_git_branch)\[\033[00m\]\$ '

# Useful aliases
alias gs='git status'
alias gl='git log --oneline --graph --all'
alias gd='git diff'
alias gc='git commit -m'
alias gp='git push'
alias gpl='git pull'
alias gco='git checkout'
alias gb='git branch'

macOS: Zsh Git Completion


# Add to ~/.zshrc
# Enable tab completion for Git
autoload -Uz compinit && compinit

# Show Git branch in prompt (using vcs_info)
autoload -Uz vcs_info
precmd_vcs_info() { vcs_info }
precmd_functions+=( precmd_vcs_info )
setopt prompt_subst
RPROMPT=\$vcs_info_msg_0_
zstyle ':vcs_info:git:*' formats ' %b'

Linux: Bash Git Completion


# Ubuntu/Debian
sudo apt install bash-completion
source /etc/bash_completion

# Fedora
sudo dnf install bash-completion

# Download completion script manually
curl -L https://raw.githubusercontent.com/git/git/master/contrib/completion/git-completion.bash -o ~/.git-completion.bash
source ~/.git-completion.bash

Cross-Platform: Essential Global Config


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

# Default branch
git config --global init.defaultBranch main

# Editor
git config --global core.editor "code --wait"

# Line endings (Windows)
git config --global core.autocrlf true

# Line endings (macOS/Linux)
git config --global core.autocrlf input

# Universal line ending handling (recommended)
git config --global core.autocrlf false
# Then use .gitattributes with: * text=auto

# Credential caching
git config --global credential.helper cache --timeout=3600

# Push default
git config --global push.default simple

# Color output
git config --global color.ui auto

# Autocorrect typos
git config --global help.autocorrect 10

Observability Checklist

Logs: Run git config --list --show-origin to see where each setting comes from
Metrics: Track git --version across your team to ensure everyone uses a compatible version
Traces: Use GIT_TRACE=1 git <command> to debug installation or configuration issues
Alerts: Monitor for deprecation warnings in Git output (e.g., core.autocrlf warnings)
Audit: Periodically review ~/.gitconfig for stale or conflicting settings
Health: Run git config --global --list after any OS update to verify settings persist
Verification: Verify installer integrity with GPG signature checks — download the signing key from git-scm.com and run gpg --verify on the downloaded installer
Version pinning: In CI/CD pipelines, pin the Git version explicitly (e.g., git version 2.45.0) rather than relying on the runner’s default, which may change unexpectedly and break builds

Security/Compliance Notes

Credential storage: Never use credential.helper store on shared machines — it saves passwords in plaintext. Use cache (memory-only, times out) or platform keychains (macOS Keychain, Windows Credential Manager)
SSH keys: Generate keys with ssh-keygen -t ed25519 -C "your.email@example.com" — Ed25519 is more secure and faster than RSA
GPG signing: Configure commit signing with git config --global commit.gpgSign true after setting up GPG keys
HTTPS vs SSH: Prefer SSH for Git operations — it uses key-based authentication rather than passwords
Proxy configuration: If behind a corporate proxy, configure it with git config --global http.proxy http://proxy.company.com:8080

Common Pitfalls / Anti-Patterns

Installing multiple Git versions: Having Git from Xcode, Homebrew, and MacPorts simultaneously causes confusion. Use which git to identify which one runs, and remove duplicates
Skipping identity configuration: Git will use your hostname as the author name, creating embarrassing commit history. Always set user.name and user.email first
Wrong line ending settings on Windows: Setting core.autocrlf false on Windows without a .gitattributes file causes cross-platform conflicts. Use true for Windows or rely on .gitattributes
Using an incompatible editor: Setting core.editor to a GUI editor without the --wait flag causes Git to think the commit message is empty. Always use --wait or -w
Not updating Git: Old Git versions lack critical features and security fixes. Update at least annually
Ignoring WSL vs Windows Git separation: Editing files in WSL and committing with Windows Git (or vice versa) causes line ending chaos. Use the Git that matches your editing environment

Quick Recap Checklist

Minimum Viable Configuration for a New Developer Machine

Interview Q&A

What is the difference between `core.autocrlf true` and `core.autocrlf input`?

core.autocrlf true converts line endings both ways: CRLF to LF on commit, and LF to CRLF on checkout. This is for Windows developers who need CRLF in their working files. core.autocrlf input converts only on commit (CRLF to LF) but does not convert on checkout. This is for macOS/Linux developers who natively use LF and should never receive CRLF files.

Why does Git require both `user.name` and `user.email` for commits?

Every Git commit embeds the author's name and email directly into the commit object. This information becomes permanent parts of the repository history — they are used for attribution, git blame, and identifying contributors. Without these settings, Git refuses to create commits to prevent anonymous or incorrect attribution. The email does not need to match any remote account, but it should be consistent for accurate history.

What does `push.default simple` do and why is it the recommended setting?

push.default simple configures git push to only push the current branch to a remote branch with the same name, and only if the upstream is already set. This prevents accidentally pushing to the wrong branch or pushing all local branches at once. Before Git 2.0, the default was matching, which pushed all branches with matching names — a dangerous behavior that caused unintended pushes.

How do you configure Git to use SSH instead of HTTPS for GitHub?

First, generate an SSH key: ssh-keygen -t ed25519 -C "your@email.com". Add the public key (~/.ssh/id_ed25519.pub) to your GitHub account settings. Then either clone with the SSH URL (git clone git@github.com:user/repo.git) or convert an existing HTTPS remote: git remote set-url origin git@github.com:user/repo.git. Verify with ssh -T git@github.com.

Resources

Git Downloads — Official downloads for all platforms
Git for Windows — Windows-specific Git distribution
Homebrew — macOS package manager
Pro Git — Getting Started — Detailed installation guide
GitHub — Connecting to GitHub with SSH — SSH setup guide
Git Credential Manager — Secure credential storage