The mailbox tradition

git am applies patches in mbox format: the format used by mailing-list-driven projects like the Linux kernel and Git itself. Each mbox entry contains a patch plus its commit metadata (author, subject, body), so applying preserves authorship.

Why patches

Patches are portable diffs you can email, paste in a ticket, or store as a file. They are how Linux kernel development works at scale and remain useful any time you need to share a change without push access to a shared remote.

A workflow, not a panic

Conflicts are routine. The right workflow turns them from a stress event into a five-minute task: inspect, decide, edit, verify, continue. This page lays out the discipline.

Step 1: inspect

git status                                # which files conflict
git diff --name-only --diff-filter=U
git log --merge -p path/to/file           # commits unique to each side

--merge shows only commits relevant to the unmerged path on each side, dramatically narrowing the search.

What is three-way

Two-way diff shows what changed between two versions. Three-way diff also considers the common ancestor, letting Git decide whether a region was changed by one side, the other, or both. Three-way is the foundation of merging.

Inspecting a conflict

During a merge, files with conflicts contain markers:

<<<<<<< HEAD
our version
=======
their version
>>>>>>> feature

Show all three sides, including the ancestor:

The unsung pseudo-refs

Beyond HEAD, Git maintains a small zoo of automatically-updated refs that record what just happened. Knowing them turns "I deleted my work" into a one-line recovery.

HEAD

Points to the current branch (e.g., ref: refs/heads/main) or, when detached, to a commit SHA directly. git symbolic-ref HEAD shows which.

Beyond the default

git log is a small query language for your history. With the right flags it produces dashboard-quality reports, audit trails, and bug forensics. This page collects the most useful incantations.

Pretty formats

git log --pretty=oneline
git log --pretty=fuller
git log --pretty=format:'%h %ad %an %s' --date=short
git log --pretty=format:'%C(yellow)%h%Creset %C(cyan)%ad%Creset %s %C(green)(%an)%Creset' --date=short

Define a permanent alias:

Editing history without rewriting it

Sometimes you want to splice histories together (a converted Subversion import meeting a continuation, for example) without rewriting commits. Grafts and the refs/replace/ namespace let Git pretend the parent of one commit is a different commit, leaving the original objects untouched.

The staging area, demystified

The index (a.k.a. cache, staging area) lives at .git/index as a binary file describing what the next commit will contain. It is not a tree — it is a flat sorted list of path entries with stat info, mode, and SHA. Operations like git add, git rm, and git mv update the index; git commit turns it into a tree object.

What is a ref

A ref is a name that points to an object — usually a commit. Branches are refs under refs/heads/, tags under refs/tags/, remote-tracking under refs/remotes/, and pseudo-refs like HEAD, FETCH_HEAD, ORIG_HEAD live at the root of .git. Internally, refs are either loose files or entries in .git/packed-refs.

Packfile basics

A packfile bundles many objects into one file with delta compression — instead of storing each version of a file in full, similar objects share a base and store only the difference. The result is a 5x to 50x size reduction on real repos. Pack files live under .git/objects/pack/ as pack-<sha>.pack with sidecar .idx and (newer) .rev files.