Git & GitHub Setup

SSH keys, commit signing, and the global config every other guide on this site quietly assumes you already have.

Every setup guide on this site assumes you can already git clone, commit, and push without thinking about it. This is the guide that actually covers getting there — identity, SSH keys, and commit signing, done once per machine.

Install Git

macOS:

brew install git

(Or trigger the Xcode Command Line Tools installer with git --version — macOS ships a Git wrapper that prompts you to install it on first use.)

Linux:

sudo apt install git      # Debian/Ubuntu
sudo dnf install git      # Fedora

Windows: install Git for Windows, or better, use WSL2 and follow the Linux instructions inside it.

Verify:

git --version

Set your identity

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

warning

Use the same email here as your GitHub account (or add it as a verified email in GitHub settings). Commits with a mismatched email still push fine, but GitHub won't link them to your profile or count them toward your contribution graph.

A couple of other global settings worth setting immediately:

git config --global init.defaultBranch main
git config --global pull.rebase false
git config --global core.editor "code --wait"

Generate an SSH key

SSH keys let you push/pull without typing a password every time.

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

Accept the default file location, set a passphrase (recommended — your SSH agent will cache it per session), then start the agent and add the key:

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

Copy the public key:

cat ~/.ssh/id_ed25519.pub

Paste it into GitHub → Settings → SSH and GPG keys → New SSH key.

Test the connection:

ssh -T git@github.com

A successful setup replies with Hi <username>! You've successfully authenticated... — note that it's not a shell login, so that message is success, not an error.

Sign your commits

GitHub shows a "Verified" badge on signed commits — good practice for any repo where provenance matters. Modern Git can sign commits with the same SSH key you just created, no separate GPG key needed:

git config --global gpg.format ssh
git config --global user.signingkey ~/.ssh/id_ed25519.pub
git config --global commit.gpgsign true

Add the same public key again on GitHub, this time under Settings → SSH and GPG keys → New SSH key, with key type set to Signing Key.

A global .gitignore

Keep editor and OS clutter (.DS_Store, .vscode/, *.swp) out of every repo's own .gitignore by handling it once, globally:

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

# ~/.gitignore_global
.DS_Store
.vscode/
*.swp

Common gotchas

warning

"Permission denied (publickey)" when pushing. Either the key isn't loaded into the agent (ssh-add -l to check), or the public key pasted into GitHub doesn't match. Re-run ssh -T git@github.com after ssh-add to confirm before blaming the remote.

warning

Commits show up as a different GitHub user, or no user at all. Your user.email doesn't match any verified email on your GitHub account. Fix it going forward with git config --global user.email, and rewrite past commits with git commit --amend --reset-author if it matters for a recent, unpushed commit.

With identity, SSH, and signing set up once, every clone/push/pull on this machine — for every project in this knowledge base — just works.