Git & GitHub

Git is a content-addressable filesystem with a VCS UI bolted on top. Every command becomes intuitive once you internalize three trees, four object types, and one immutable history graph.

The three trees

Almost every Git command moves data between these three locations. Understanding which is which removes 90% of beginner confusion.

The four object types

Branches and lightweight tags are not objects — they are refs: tiny text files in .git/refs/ containing a single SHA. Cheap to create, cheap to delete.

The agentic Git loop

1. Modify files in the working directory.
2. Stage a logical chunk with git add.
3. Commit the snapshot to the repository.
4. Branch, merge, rebase to organize history.
5. Push to a remote so others can pull.

Git vs. GitHub

Git is the engine — runs locally, no network needed, written by Linus Torvalds in 2005. GitHub is a hosting service built around Git that adds pull requests, issues, code review, and CI. You can use Git without GitHub. You cannot use GitHub without Git.

Pick the right installer for your OS, set your identity once globally, and configure a sane default editor and branch name. Skipping these steps now means fixing wrong-author commits later.

# macOS — Homebrew (recommended)
brew install git
brew upgrade git

# macOS — built-in via Xcode CLT
xcode-select --install

# Linux — Debian/Ubuntu
sudo apt update && sudo apt install git

# Linux — Fedora
sudo dnf install git

# Linux — Arch
sudo pacman -S git

# Windows — winget
winget install --id Git.Git -e

# Windows — Chocolatey / Scoop
choco install git
scoop install git

# Verify
git --version

# macOS
brew install gh

# Windows
winget install --id GitHub.cli

# Linux — Debian/Ubuntu
sudo apt install gh

# First-time auth (HTTPS, browser flow)
gh auth login

# Set globally — applies to all repos
git config --global user.name "Your Name"
git config --global user.email "you@example.com"

# Verify
git config --global --list

# Per-repo override (work vs. personal)
cd /path/to/work-repo
git config user.email "you@company.com"

# Use 'main' for new repos (matches GitHub default)
git config --global init.defaultBranch main

# Default editor
git config --global core.editor "code --wait"     # VS Code
git config --global core.editor "vim"             # Vim
git config --global core.editor "nano"            # Nano

# Pull = fast-forward only (avoid noisy merge commits)
git config --global pull.ff only

# Auto-prune deleted remote branches on fetch
git config --global fetch.prune true

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

# Better diffs (zdiff3 shows base + ours + theirs)
git config --global merge.conflictStyle zdiff3

# Reuse recorded conflict resolutions
git config --global rerere.enabled true

SSH keys for GitHub

# Generate ed25519 key (modern; preferred over RSA)
ssh-keygen -t ed25519 -C "you@example.com"

# Start agent and add key
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

# Copy public key to clipboard
pbcopy < ~/.ssh/id_ed25519.pub        # macOS
xclip -sel clip < ~/.ssh/id_ed25519.pub  # Linux
cat ~/.ssh/id_ed25519.pub | clip       # Windows

# Add to GitHub via CLI (no browser needed)
gh ssh-key add ~/.ssh/id_ed25519.pub --title "laptop"

# Test the connection
ssh -T git@github.com

Three ways to land in a repo: init a new one, clone someone else's, or cd into a folder that already has a .git. Every other command fans out from there.

# Initialize an empty repo in current directory
git init

# Initialize with a specific default branch
git init --initial-branch=main
git init -b main

# Clone over HTTPS
git clone https://github.com/owner/repo.git

# Clone over SSH (preferred for write access)
git clone git@github.com:owner/repo.git

# Clone into a custom directory name
git clone <url> my-folder

# Shallow clone — fetch only last N commits (faster)
git clone --depth 1 <url>

# Single-branch shallow (CI-friendly)
git clone --depth 1 --single-branch --branch main <url>

# Partial clone — defer blob downloads
git clone --filter=blob:none <url>

# Clone with submodules in one step
git clone --recurse-submodules <url>

# Where is the repo root? (works from any subdir)
git rev-parse --show-toplevel

# Are we in a repo at all?
git rev-parse --is-inside-work-tree

# Working tree status
git status              # full
git status -s           # short / porcelain
git status -sb          # short + branch info

# Verify object database integrity
git fsck --full

# Pack and prune unreachable objects
git gc                   # normal
git gc --aggressive      # slower, deeper packing

# Repo size on disk
git count-objects -vH

The .gitignore file

# Logs & runtime
*.log
*.pid

# Dependencies
node_modules/
vendor/
.venv/

# Build output
dist/
build/
*.exe

# OS noise
.DS_Store
Thumbs.db

# Editor / IDE
.vscode/
.idea/
*.swp

# Secrets — NEVER commit these
.env
.env.local
*.key
*.pem

Already-tracked files are not retroactively ignored. To ignore something already committed:

# Stop tracking but keep the file on disk
git rm --cached path/to/file
git commit -m "stop tracking file"

For machine-local ignores that shouldn't be shared with the team, edit .git/info/exclude instead of .gitignore.

A commit should be one logical change. Stage with surgical care; commit messages outlive the code.

Staging files

Committing

Patch-mode workflow Pro

# Step into hunks one at a time
git add -p

# Inside the prompt:
#   y - stage this hunk        n - skip it
#   s - split into smaller     e - edit hunk by hand
#   q - quit                   ? - help

Patch mode is how you turn a messy day's worth of changes into a clean sequence of atomic commits without abandoning work.

Conventional Commits — recommended message format

type(scope)!: subject

[optional body]

[optional footer(s)]

Append ! after the type/scope to flag a breaking change: feat(api)!: drop /v1 endpoints. The Conventional Commits spec drives changelog generators (commitizen, standard-version, release-please) and semver automation.

Commit message — the seven rules

• Separate subject from body with a blank line.
• Limit subject to 50 chars; wrap body at 72.
• Capitalize the subject line.
• Don't end the subject with a period.
• Use the imperative mood: "Add login button", not "Added" or "Adds".
• Body explains what and why, not how.
• Reference issues / PRs in the footer (Closes #123).

git log alone is configurable enough to replace half of what most people use GUIs for. Learn five flags and you'll never need a separate tool.

The essential log incantations

# Default — newest first, full message
git log

# One-liner per commit
git log --oneline

# Branchy ASCII graph (worth aliasing)
git log --oneline --graph --all --decorate

# Show files changed in each commit
git log --stat

# Show full patches
git log -p

# Limit number of commits
git log -n 5

# Filter by author
git log --author="Dimitris"

# Filter by message content
git log --grep="fix login"

# Filter by content change (pickaxe)
git log -S "function deprecated_thing"

# Filter by date
git log --since="2 weeks ago" --until="yesterday"

# Files changed only in a specific path
git log -- path/to/file
git log --follow -- path/to/file   # follow renames

# Pretty custom format
git log --pretty=format:"%h %ad | %s%d [%an]" --date=short

Inspect a single commit

Who changed what — blame and friends

# Line-by-line authorship
git blame path/to/file

# Limit to a line range
git blame -L 50,80 path/to/file

# Ignore whitespace-only changes
git blame -w path/to/file

# Detect moved/copied lines (slower, more accurate)
git blame -C -C path/to/file

# Ignore noisy reformatting commits
git config blame.ignoreRevsFile .git-blame-ignore-revs
git blame --ignore-revs-file=.git-blame-ignore-revs path/to/file

Refspec shorthand cheat-sheet

Bisect — binary-search for the breaking commit

git bisect start
git bisect bad                # current commit is broken
git bisect good v1.4.0        # this older tag was fine

# Git checks out the midpoint commit. Run your test, then mark:
git bisect bad        # or  git bisect good

# Repeat until Git prints "<sha> is the first bad commit"
git bisect reset      # return to where you started

# Fully automated with a test script (exits 0/1 = good/bad)
git bisect run ./test.sh

Every git diff answers one question: what's different between A and B? A and B can be the working tree, the index, a commit, a branch, or a tag. Knowing which two things you're comparing is the whole game.

The four canonical diffs

--cached is an alias for --staged. Both work the same way; modern Git prefers --staged.

Useful narrowing

# Diff a single file
git diff -- path/to/file

# Diff two branches
git diff main..feature

# Just the file names that differ
git diff --name-only main..feature

# File names + add/delete/modify status
git diff --name-status main..feature

# Per-file change summary
git diff --stat HEAD~5

# Word-level instead of line-level diff
git diff --word-diff

# Ignore whitespace
git diff -w
git diff --ignore-all-space

# Show inter-hunk context (default 3 lines)
git diff -U10            # 10 lines of context

Reading a diff

diff --git a/file.txt b/file.txt
index e69de29..d95f3ad 100644
--- a/file.txt          // 'a' = old version
+++ b/file.txt          // 'b' = new version
@@ -1,3 +1,4 @@         // hunk header: -old_start,old_count +new_start,new_count
 unchanged line
-removed line
+added line
+another added line
 unchanged line

Range-diff — "what changed about my changes?" Modern

# Compare two versions of the SAME branch (e.g. before/after rebase)
git range-diff main..feature@{1} main..feature

# Compare two patch series
git range-diff <base1>..<tip1> <base2>..<tip2>

git range-diff is invaluable for code review when a PR has been force-pushed: it shows what changed between iterations, not just the latest version.

Diff tools — visualizing in your editor

# Configure VS Code as your diff tool
git config --global diff.tool vscode
git config --global difftool.vscode.cmd 'code --wait --diff $LOCAL $REMOTE'

# Run the configured diff tool
git difftool

# Skip the "are you sure?" prompt
git difftool --no-prompt

Modern Git splits "undo" into three commands with three clear domains: restore for files, revert for committed history that's been shared, reset for committed history that's still local. Pick the right one and you'll never lose work.

git restore — undo file-level changes Modern

Replaces the file-restoring half of legacy git checkout. Cleaner, less overloaded, harder to misuse.

git revert — undo a commit by adding a new one

Safe for shared/pushed history. Creates a new commit that undoes the changes of the target commit, leaving original history intact.

# Revert a single commit (opens editor for message)
git revert <sha>

# Revert without committing — leaves changes staged
git revert -n <sha>

# Revert a range (newer first, in reverse)
git revert HEAD~3..HEAD

# Revert a merge commit — must specify which parent's history to keep
git revert -m 1 <merge-sha>

# Abort an in-progress revert
git revert --abort
git revert --continue
git revert --skip

git reset — rewind local history Local only

Three modes — same target, different effect on your working tree and index:

# Unstage a file (mixed reset of one file)
git reset HEAD path/to/file
# —or, more clearly, the modern equivalent —
git restore --staged path/to/file

# Undo last commit, keep changes staged
git reset --soft HEAD~1

# Undo last commit, keep changes in working tree (unstaged)
git reset HEAD~1
git reset --mixed HEAD~1     # same thing, explicit

# Nuke last commit AND its changes — gone from working tree
git reset --hard HEAD~1

# Reset current branch to match remote exactly
git fetch origin
git reset --hard origin/main

The decision matrix

A branch is a 41-byte text file containing a SHA. Creating one is instant. Deleting one is reversible (within reflog window). This cheapness is why Git workflows revolve around them.

Modern branching with git switch Modern

git switch handles only branch movement — clearer and safer than legacy git checkout.

Branch listing & management

HEAD — the moving finger

HEAD is a pointer to the current branch (which itself points to a commit). When you commit, the branch advances and HEAD goes along for the ride.

A detached HEAD means HEAD points directly to a commit instead of a branch. New commits made there are orphaned — they belong to no branch and will eventually be garbage-collected. Always either return to a real branch or convert the detached state into a new branch:

# Detached state — exploring an old commit
git switch --detach v1.2.0

# Make some experimental commits...

# Save them by creating a branch HERE
git switch -c experimental

# Or discard and return to safety
git switch -          # back to where you were
git switch main

Renaming the default branch master → main

# Rename locally
git branch -m master main

# Push the new branch and set its upstream
git push -u origin main

# Update HEAD on the remote (then change default in GitHub UI/CLI)
gh repo edit --default-branch main

# Delete the old remote branch
git push origin --delete master

Merging integrates one branch's history into another. The result depends on the shape of the history and the strategy you pick.

Three merge shapes

The merge commands

Typical feature-branch merge

# Update main
git switch main
git pull

# Merge feature into main
git merge feature/auth-oauth

# Push the result
git push

# Delete the feature branch (locally and remotely)
git branch -d feature/auth-oauth
git push origin --delete feature/auth-oauth

Resolving merge conflicts

When the same lines of the same file change on both sides, Git stops mid-merge and asks you to resolve. Files containing conflicts get markers:

<<<<<<< HEAD
this is what's on the branch you're merging INTO
||||||| merged common ancestor (with merge.conflictStyle=zdiff3)
this is the original
=======
this is what's on the branch you're merging IN
>>>>>>> feature/auth

# 1. See which files have conflicts
git status

# 2. Open each, edit to the desired final state, remove all markers

# 3. Stage resolved files
git add path/to/conflicted-file

# 4. Once everything is staged, finalize the merge
git merge --continue
# —or simply—
git commit

# Bail out at any point
git merge --abort

Conflict-resolution helpers

Squash merge — when and why

Squashing turns a feature branch's many WIP commits into one tidy commit on the target. Useful for noisy branches but loses the granular history. GitHub's "Squash and merge" PR option does this remotely.

git switch main
git merge --squash feature/messy-branch
git commit -m "feat(api): add bulk export endpoint"

Stashes save uncommitted work to a stack you can pop later. Perfect for "I need to switch branches right now and don't want to commit half-baked changes."

Core stash commands

Common stash recipes

# Quick switch — stash, branch, work, come back
git stash push -m "wip: refactoring auth"
git switch hotfix/login
# ...fix the hotfix, commit, push...
git switch -
git stash pop

# Stash including untracked .env.local you forgot
git stash push -u -m "wip with new env file"

# Apply a specific old stash by index
git stash list
#   stash@{0}: wip: third attempt
#   stash@{1}: wip: working version
#   stash@{2}: wip: original idea
git stash apply stash@{1}

# Recover a "lost" pop — conflict bailout
git stash apply stash@{0}     # try again

# Convert stash into a real branch (keeps the stash)
git stash branch feature/from-stash stash@{0}

A remote is just a nickname for a URL. origin is the conventional name for the repo you cloned from. upstream is the conventional name for the original repo when you've forked. Every Git operation that touches the network names a remote (sometimes implicitly).

Managing remotes

Adding upstream after forking

# After cloning your fork:
git remote -v
# origin  git@github.com:you/project.git (fetch)
# origin  git@github.com:you/project.git (push)

# Add the original repo as 'upstream'
git remote add upstream https://github.com/original/project.git

# Verify
git remote -v

# Sync from upstream periodically
git fetch upstream
git switch main
git merge upstream/main
git push origin main

Switching protocols (HTTPS ↔ SSH)

# Currently HTTPS, switch to SSH
git remote set-url origin git@github.com:owner/repo.git

# Currently SSH, switch to HTTPS
git remote set-url origin https://github.com/owner/repo.git

Pushing — local → remote

Remote-tracking branches

When you fetch, Git updates remote-tracking branches: read-only local pointers like origin/main that mirror the remote's state at last fetch. They are not the same as your local main.

fetch is the safe inspection step. pull is fetch + integrate in one command. When in doubt, fetch first.

git fetch — download without merging

git pull — fetch + integrate

git pull is shorthand for two commands: git fetch then either git merge or git rebase depending on configuration.

Recommended pull config

# Make pull fail loudly if a fast-forward isn't possible —
# forces an explicit merge or rebase decision.
git config --global pull.ff only

# Always auto-prune deleted remote branches
git config --global fetch.prune true

If you prefer rebase-by-default for cleaner history (and no merge bubbles on every pull):

git config --global pull.rebase true
git config --global rebase.autoStash true

Pull with conflicts

# Merge-style conflict
git pull
# <CONFLICT messages>
# Resolve files, stage, commit
git add <resolved-files>
git commit

# Rebase-style conflict
git pull --rebase
# <CONFLICT messages>
git add <resolved-files>
git rebase --continue
# —or bail out—
git rebase --abort

fetch vs. pull — the rule of thumb

Use git fetch before reviewing what teammates have done; use git pull when you're ready to integrate.

Rebasing rewrites history by replaying commits one at a time onto a new base. Used wisely it produces beautiful linear history. Used carelessly it destroys collaborators' work.

The rebase mental model

Where merge joins two histories with a merge commit, rebase takes commits from one branch and re-applies them onto another, creating new commits with new SHAs. The original commits are abandoned (but recoverable via reflog).

Basic rebase

Standard "update my feature branch" flow

# On your feature branch, get latest main
git fetch origin
git rebase origin/main

# If conflicts:
#   1. Edit conflicted files
#   2. git add <resolved>
#   3. git rebase --continue

# Force-push the rewritten branch (yours, not shared)
git push --force-with-lease

Interactive rebase — the history sculptor Pro

# Edit the last 5 commits
git rebase -i HEAD~5

# Edit everything since branching from main
git rebase -i main

An editor opens with one line per commit. Change the leading word to apply an action:

The fixup workflow — clean history without the hassle

# 1. Discover a small mistake in commit abc1234
#    Stage your fix, then:
git commit --fixup abc1234

# 2. Repeat for any other late fixes

# 3. Auto-squash all fixups into their targets
git rebase -i --autosquash main

With git config --global rebase.autoSquash true, every interactive rebase automatically reorders fixup! commits next to their targets. Combined with commit --fixup, it's the cleanest possible workflow.

Comparing pre/post rebase — range-diff

# Before forcing the push, see what really changed
git rebase main
git range-diff main feature@{1} feature

Rebase vs. merge — the trade-off

Tags are immutable named pointers to a commit — perfect for marking releases. Two flavors: lightweight (a ref pointing at a commit, like a stationary branch) and annotated (a full Git object with a message, signature, and metadata).

Tag commands

Annotated vs. lightweight

Semantic Versioning quick reference

MAJOR.MINOR.PATCH

MAJOR  — incompatible API changes
MINOR  — backwards-compatible new features
PATCH  — backwards-compatible bug fixes

# Pre-release / build metadata
v1.2.0-alpha.1
v1.2.0-beta.3
v1.2.0-rc.1
v1.2.0+20251231

See the full Semantic Versioning 2.0.0 spec for canonical rules.

Releases via GitHub CLI

# Create a release linked to a tag
gh release create v1.0.0 \
  --title "v1.0.0 — Initial release" \
  --notes "First public release"

# Auto-generate notes from PRs since last tag
gh release create v1.1.0 --generate-notes

# Mark as pre-release
gh release create v1.2.0-rc.1 --prerelease

# Attach binaries
gh release create v1.0.0 ./dist/app-*.tar.gz

# List, view, edit, delete
gh release list
gh release view v1.0.0
gh release edit v1.0.0 --notes "Updated notes"
gh release delete v1.0.0

Useful describe

# "Most recent tag, plus how far we've come"
git describe
# v1.2.0-15-g8f3c2a1
# —15 commits past v1.2.0, current SHA starts with 8f3c2a1

# Only annotated tags (default)
git describe

# Include lightweight tags too
git describe --tags

# Always print short SHA, even on a tag
git describe --always

The reflog records every move HEAD makes — every commit, switch, reset, rebase. It's how you recover from "I think I just deleted everything." Local-only, kept for ~90 days by default.

Reading the reflog

# Sample output
8f3c2a1 HEAD@{0}: rebase (finish): returning to refs/heads/feature
8f3c2a1 HEAD@{1}: rebase (pick): apply migration
6e9b1f0 HEAD@{2}: rebase (start): checkout main
ab12cd3 HEAD@{3}: commit: WIP — broken state
4f5d6c7 HEAD@{4}: commit: stable feature work

The rescue patterns

1. "I just did a hard reset and lost commits"

git reflog
# Find the SHA from BEFORE the reset
git reset --hard ab12cd3

2. "I deleted a branch with unmerged work"

# Reflog still has it (if < 30 days for unreachable, ~90 for reachable)
git reflog                   # find the last SHA the branch pointed to
git switch -c recovered <sha>

3. "I rebased and the result is wrong"

git reflog
# Find HEAD@{N} where N is just before "rebase (start)"
git reset --hard HEAD@{4}

4. "I dropped a stash by accident"

# Stash drops aren't in HEAD's reflog — check stash's own reflog
git fsck --no-reflog | grep "dangling commit"
# Or, if you have the SHA:
git stash apply <sha>

Time-relative refs — sometimes faster than reflog

git switch main@{yesterday}
git diff main@{1.week.ago}..main
git log feature@{2.hours.ago}..feature

# Index notation (Nth move ago)
git switch main@{3}    # 3 reflog entries back

Garbage collection & reflog expiration

Git eventually prunes unreachable objects to save space. Defaults:

• Reachable reflog entries expire after 90 days (gc.reflogExpire)
• Unreachable reflog entries expire after 30 days (gc.reflogExpireUnreachable)
• git gc --prune=now immediately deletes anything older than the cutoff

# Expire reflog entries manually
git reflog expire --expire=30.days --all

# Pause expiration on a critical branch
git config branch.<name>.reflogExpire never
git config branch.<name>.reflogExpireUnreachable never

fsck — find lost commits beyond reflog

# List dangling objects (commits, blobs, trees no ref points to)
git fsck --lost-found
git fsck --no-reflog

# Inspect a candidate
git show <dangling-sha>

# Recover
git switch -c rescued <dangling-sha>

Worktrees — multiple checked-out branches at once

One repo, many working directories. Eliminates the "stash, switch, rebuild, switch back" dance for hotfixes. Each worktree has its own working tree and index but shares the object database.

Hotfix-while-feature pattern

# You're in the middle of feature/auth, suddenly a P0 bug
cd ~/projects/myapp
git worktree add ../myapp-hotfix -b hotfix/critical main

# In a new terminal:
cd ../myapp-hotfix
# —fix, commit, push, open PR—
gh pr create --base main --title "Fix critical login bug"

# Back in original terminal, your feature work is untouched
cd ~/projects/myapp
# —continue feature work—

# When hotfix is merged, clean up
git worktree remove ../myapp-hotfix
git branch -d hotfix/critical

Sparse-checkout — partial working tree

Useful in monorepos: only check out the directories you actually work in. Saves disk space and speeds up status / diff.

# Practical example: monorepo with apps/, libs/, infra/
git clone --filter=blob:none --no-checkout git@github.com:org/monorepo.git
cd monorepo
git sparse-checkout init --cone
git sparse-checkout set apps/web libs/shared
git switch main
# Only apps/web and libs/shared materialize on disk

Bundles — repos as files

A bundle is a single file containing Git history — useful when you can't push/pull (air-gapped systems, sneakernet across networks).

Maintenance — keep big repos fast Modern

# Register repo for background maintenance (gc, pack, prefetch)
git maintenance start

# Run a maintenance task right now
git maintenance run --task=gc
git maintenance run --task=prefetch

# Stop scheduled tasks
git maintenance stop

git maintenance sets up cron / launchd / systemd timers to keep your repo healthy. Especially useful in monorepos where manual git gc would otherwise take ages.

Underneath the porcelain (the user-facing commands) sits the plumbing: low-level commands that operate directly on Git's object database. You almost never need them — but understanding them is the difference between using Git and knowing Git.

Inspecting the object database

Creating objects manually — what git add + git commit really do

# 1. Hash a file's contents into a blob
echo "hello world" | git hash-object --stdin -w
# → 3b18e512dba79e4c8300dd08aeb37f8e728b8dad

# 2. Read it back
git cat-file -p 3b18e512dba79e4c8300dd08aeb37f8e728b8dad

# 3. Build a tree containing that blob
git update-index --add --cacheinfo 100644 \
  3b18e512dba79e4c8300dd08aeb37f8e728b8dad hello.txt
git write-tree
# → 68aba62e560c0ebc3396e8ae9335232cd93a3f60

# 4. Create a commit pointing to that tree
echo "first commit" | git commit-tree 68aba62e -p HEAD
# → new commit SHA

# 5. Move the branch ref
git update-ref refs/heads/main <new-commit-sha>

That sequence — hash-object, update-index, write-tree, commit-tree, update-ref — is exactly what git add + git commit automate.

Refs and symbolic refs

The hashing function

Object SHAs are deterministic: the same content always produces the same SHA. The hash is computed over "<type> <size>\0<content>" — that's why an empty file isn't all zeros.

Modern Git supports SHA-256 in addition to SHA-1. Set on init:

git init --object-format=sha256

Most servers (including GitHub at the time of writing) still use SHA-1; SHA-256 is opt-in until ecosystem support is universal.

Trailers — structured commit metadata

# Add a Co-authored-by trailer (GitHub honors these for credit)
git commit -m "feat: pair-programmed feature" \
  --trailer "Co-authored-by: Alex Smith <alex@example.com>"

# Read trailers from existing commits
git log --format='%(trailers)' -n 5

# Interpret programmatically
git interpret-trailers --parse < commit-msg.txt

Config scopes — first match wins

Config commands

Conditional includes — different identity per directory

# ~/.gitconfig
[user]
    name = Dimitris
    email = dimitris@personal.com

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

# ~/.gitconfig-work
[user]
    email = dimitris@company.com
[commit]
    gpgsign = true

Now any repo under ~/work/ uses your work email automatically. gitdir/i: is the case-insensitive variant; onbranch: matches by branch name.

Aliases — the heart of a productive setup

# Set via command line
git config --global alias.s "status -sb"
git config --global alias.co "switch"
git config --global alias.cb "switch -c"
git config --global alias.unstage "restore --staged"

# Pretty graph log — the legend
git config --global alias.lg \
  "log --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"

# Last commit, full diff
git config --global alias.last "log -1 HEAD --stat"

# What did I do today?
git config --global alias.today \
  "log --since='6 am' --author='Dimitris' --pretty=format:'%h %s'"

# Branches sorted by recent activity
git config --global alias.recent \
  "for-each-ref --sort=-committerdate refs/heads/ --format='%(committerdate:short) %(refname:short)'"

# Quick amend with no message edit
git config --global alias.fixlast "commit --amend --no-edit"

# Show who's been touching a file (with renames)
git config --global alias.who "shortlog -sn --no-merges --follow --"

Direct .gitconfig editing — easier for many aliases

# ~/.gitconfig
[alias]
    s = status -sb
    co = switch
    cb = switch -c
    unstage = restore --staged
    last = log -1 HEAD --stat
    lg = log --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit

    # Shell-out aliases prefix with "!"
    pushf = "!git push --force-with-lease"
    nuke = "!git reset --hard origin/$(git symbolic-ref --short HEAD)"

Recommended global config — battle-tested defaults

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

[init]
    defaultBranch = main

[pull]
    ff = only

[fetch]
    prune = true
    pruneTags = true

[merge]
    conflictStyle = zdiff3

[rebase]
    autoSquash = true
    autoStash = true

[rerere]
    enabled = true

[diff]
    algorithm = histogram
    colorMoved = default
    mnemonicPrefix = true

[push]
    autoSetupRemote = true
    followTags = true

[commit]
    verbose = true

commit.verbose = true shows the diff in your editor when writing a commit message — invaluable for catching last-minute mistakes.

The GitHub CLI (gh) is the official terminal interface to GitHub. Pull requests, issues, releases, code review, repo creation — all of it without context-switching to a browser.

Auth & account

Repos — create, clone, fork

Pull requests — the bread and butter

Typical PR workflow

# 1. Branch and work
git switch -c feature/api-rate-limit
# —edit, commit—
git push -u origin feature/api-rate-limit

# 2. Open PR
gh pr create --base main --fill --reviewer alice,bob

# 3. Watch CI
gh pr checks --watch

# 4. Address review feedback
# —edit, commit, push—
gh pr comment --body "Updated based on feedback, please re-review"

# 5. Auto-merge once approved + CI green
gh pr merge --squash --auto --delete-branch

Issues

Branch protection — set rules from CLI

# Require PR reviews + passing checks via gh api
gh api -X PUT repos/:owner/:repo/branches/main/protection \
  -f required_status_checks='{"strict":true,"contexts":["ci"]}' \
  -f enforce_admins=true \
  -f required_pull_request_reviews='{"required_approving_review_count":1}' \
  -f restrictions=null

Other useful gh commands

Markdown & READMEs — the project face

Every repo's README is rendered Markdown. It's the project's homepage on GitHub. Conventions worth following:

• Project title (H1) + one-sentence description
• Status badges (CI, version, license)
• Quickstart — fewest steps to running
• Installation, configuration, usage examples
• Contributing guidelines (or link to CONTRIBUTING.md)
• License section pointing to LICENSE file

For collaborative projects, also commit:

• .github/CODEOWNERS — auto-assign reviewers
• .github/PULL_REQUEST_TEMPLATE.md — PR description scaffold
• .github/ISSUE_TEMPLATE/*.yml — structured issue forms
• SECURITY.md — vulnerability reporting
• CONTRIBUTING.md — how to contribute

Starting points, not scripture. Mix and match for your team's risk tolerance, deployment cadence, and code-review culture.

1. The classic feature branch

# Update main
git switch main
git pull

# Branch off
git switch -c feature/oauth-login

# Work in atomic commits
# —edit, git add -p, git commit—

# Push and open PR
git push -u origin feature/oauth-login
gh pr create --fill

# Once approved + CI passes
gh pr merge --squash --delete-branch
git switch main
git pull --prune

2. Fork & pull request (open-source contribution)

# 1. Fork on GitHub, then clone YOUR fork
gh repo fork upstream-owner/project --clone --remote
cd project

# Now: origin = your fork, upstream = original repo
git remote -v

# 2. Always branch from a fresh upstream main
git fetch upstream
git switch -c fix/typo-readme upstream/main

# 3. Work, commit, push to YOUR fork
git push -u origin fix/typo-readme

# 4. Open PR against upstream
gh pr create --repo upstream-owner/project --base main

# 5. Keep your fork in sync
git switch main
git fetch upstream
git merge upstream/main
git push origin main

3. Trunk-based development

Short-lived branches (hours, not days), all merging to main. Feature flags gate incomplete work in production. Best for high-cadence, well-tested teams.

git switch main && git pull
git switch -c task/short-lived
# —commit, push, PR, merge within the day—

# In code, gate the new behavior
if (featureFlags.isEnabled('new-checkout')) { ... }

4. GitFlow — long-lived branches

For projects with formal release cycles. Branches:

• main — production
• develop — integration branch for next release
• feature/* — branch from develop, merge back
• release/* — stabilize a release, merge into both main and develop
• hotfix/* — branch from main, merge into both

More overhead than trunk-based. Use only if you have multiple production versions in the wild simultaneously.

5. The atomic-commit + fixup workflow

# Set once
git config --global rebase.autoSquash true
git config --global rebase.autoStash true

# Day's work — clean commits as you go
git add -p && git commit -m "feat(api): add /users endpoint"
git add -p && git commit -m "test(api): cover /users edge cases"

# Notice a typo in the first commit?
git add . && git commit --fixup HEAD~1

# Before pushing, auto-squash all fixups in place
git rebase -i --autosquash main

# Final, clean push
git push -u origin feature/users-api

6. Hotfix while mid-feature

# You're deep in feature/auth, P0 bug reported on main
git stash push -m "wip: auth refactor"
git switch main && git pull
git switch -c hotfix/login-500
# —fix, test, commit, push, PR, merge—
gh pr create --fill --label hotfix
gh pr merge --squash --delete-branch

# Back to feature work
git switch -
git stash pop

Or, with worktrees (no stashing needed):

git worktree add ../app-hotfix -b hotfix/login-500 main
cd ../app-hotfix
# —fix in parallel terminal—
gh pr create --fill --label hotfix
cd - && git worktree remove ../app-hotfix

7. CI automation snippets

# GitHub Actions — auto-merge on label
# .github/workflows/automerge.yml
name: Auto-merge
on:
  pull_request:
    types: [labeled]
jobs:
  merge:
    if: github.event.label.name == 'auto-merge'
    runs-on: ubuntu-latest
    steps:
      - run: gh pr merge --squash --auto --delete-branch ${{ github.event.pull_request.number }}
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

8. Release tagging — manual

# From clean main
git switch main && git pull

# Annotated, signed tag
git tag -s v1.4.0 -m "Release 1.4.0 — payments + i18n"

# Push tag (and trigger your release workflow)
git push origin v1.4.0

# Create the GitHub release with auto-generated notes
gh release create v1.4.0 --generate-notes --verify-tag

9. Bisect-driven debugging

# Save a one-line repro test
cat > /tmp/test.sh <<'EOF'
#!/bin/sh
npm install --silent && npm test -- --silent regression/login
EOF
chmod +x /tmp/test.sh

git bisect start
git bisect bad HEAD
git bisect good v1.3.0
git bisect run /tmp/test.sh
git bisect reset

Git auto-finds the breaking commit out of potentially hundreds in 10–20 steps. Worth investing 5 minutes in a clean repro script.

10. Branch cleanup

# See branches already merged into main
git branch --merged main

# Delete all of them in one go (skip main itself)
git branch --merged main | grep -v "^\*\|main\|develop" | xargs -r git branch -d

# Prune stale remote-tracking refs
git fetch --prune --prune-tags

# Find branches with no upstream (fork-style stale)
git for-each-ref --format='%(refname:short) %(upstream:short)' refs/heads/ \
  | awk '$2 == ""'

Best practices

• Commit early, commit often. Rewrite later with rebase. Frequent commits make recovery and bisecting trivial.
• One commit = one logical change. If your message has "and" in it, it should probably be two commits.
• Imperative mood in commit messages. "Add login button", not "Added" / "Adds". Subject < 50 chars; wrap body at 72.
• Pull with --ff-only by default. Forces an explicit decision (merge vs. rebase) when histories diverge.
• Always --force-with-lease, never plain --force. Protects against silently overwriting a teammate's push.
• Annotated tags only for releases. Lightweight tags lose context; annotated tags carry message + signer + date.
• Set up rerere. Once you've resolved a conflict once, Git remembers it. Saves hours during long-lived rebases.
• Use zdiff3 conflict style. Shows the original alongside both sides — radically easier to resolve.
• Use commit.verbose=true. Shows the diff inline when writing your commit message — catches mistakes before they ship.
• Pre-commit hooks save reviews. Lint + format + run unit tests before commit. Use pre-commit or husky.
• One .gitignore per repo, not per directory. Easier to audit and maintain.
• Never commit secrets. If you do, rotate immediately — rewriting history won't help if it was pushed.
• Sign your commits (commit.gpgsign=true) for repos that care about authorship integrity.
• Use .git-blame-ignore-revs for noisy reformatting commits, so blame stays useful.
• Tag releases, branch features, fork forks. Don't tag for trivia; don't branch for tasks that take 10 minutes; don't fork what you can clone.

Common gotchas

• git checkout is overloaded. Modern Git replaces it with git switch (branches) and git restore (files). Use them — fewer ways to misfire.
• Detached HEAD ≠ broken. It's just HEAD pointing at a commit instead of a branch. Make new commits there at your own peril — they have no branch and will be GC'd unless you save them with git switch -c.
• Already-tracked files are NOT retroactively ignored. Adding to .gitignore after committing does nothing. Use git rm --cached to stop tracking.
• git pull = fetch + merge. If main has diverged and pull.ff is unset, you'll get a surprise merge commit. Set pull.ff=only.
• Rebasing rewrites SHAs. Force-pushing a rebased branch breaks anyone who pulled the old version. Coordinate or use --force-with-lease.
• Stashing untracked files needs -u. By default, git stash ignores untracked files. They stay in your working tree if you switch branches.
• git stash pop can leave the stash dropped on conflict. Use git stash apply when uncertain.
• git reset --hard destroys uncommitted changes silently. Reflog won't save them — they were never committed. Stash first.
• Reflog is local. A fresh git clone has no reflog history. Don't rely on it after cloning.
• Tags don't push automatically. Use git push --tags or git push --follow-tags, or set push.followTags=true.
• Submodules are a footgun. Prefer monorepos, package managers, or git subtree where possible. If you must, always use git clone --recurse-submodules.
• git revert on a merge commit needs -m. You must specify which parent's history to keep (usually -m 1).
• Line endings. Mixed CRLF/LF causes phantom diffs across Windows/macOS/Linux. Set core.autocrlf=input on Mac/Linux, true on Windows. Or commit a .gitattributes with * text=auto eol=lf.
• Filename case insensitivity (macOS/Windows). FOO.md and foo.md are the same file on case-insensitive filesystems but different in Git's index. Set core.ignoreCase=false with caution.
• Large files. Git stores entire copies of every version of every file. For binaries, use Git LFS or external storage.
• Time zones in git log. By default, dates show in author's TZ. Use --date=local or --date=iso-strict for consistency.
• Squash merges break branch parentage. The squashed commit is unrelated to the original feature branch's commits — Git can't tell they were "the same work" later.

Recovery cheat-sheet

Performance & large repo tips

• Enable git maintenance start for background gc/prefetch.
• Use partial clone (--filter=blob:none) to defer blob downloads.
• Use sparse-checkout in monorepos to materialize only the dirs you need.
• Set fetch.writeCommitGraph=true for faster git log on big repos.
• Use core.fsmonitor=true to avoid scanning the working tree on every command.
• Repack with git repack -ad --depth=50 --window=250 for major space savings.

Security

• Sign commits and tags. Configure user.signingkey + commit.gpgsign=true + tag.gpgsign=true. Modern Git supports SSH signing too.
• Verify signatures. git log --show-signature / git verify-tag <tag>.
• Branch protection on main. Require PR + reviews + CI checks. Block force-pushes.
• Secret scanning. GitHub catches some leaks automatically; pair with pre-commit secret scanners (gitleaks, trufflehog).
• Audit dependencies. Dependabot for npm/pypi/cargo, weekly. Renovate for more nuanced rules.
• Two-factor auth. Required for GitHub contributors as of 2024. Use a hardware key if possible.