Why squash

A feature branch often accumulates "WIP", "fix typo", and "address review" commits that bury intent. Squashing condenses these into a small number of logically meaningful commits before merging. Reviewers see clean history; bisect works on real units of change.

Squash on merge

The simplest approach: let the merge collapse the branch:

git checkout main
git merge --squash feature
git commit -m "Add feature X"

This stages the cumulative diff and you write a single commit message. The downside: the branch's history is lost.

Incident response

You committed an API key, password, or private key. Removing it from the latest commit is not enough — Git keeps the file in every previous commit until you rewrite history. This page walks through the full incident response.

Step 1: rotate immediately

Before touching the repo, revoke the credential. Assume any pushed history has already been mirrored, scraped, or cached by GitHub's archive program. Rotating is the only true fix; rewriting just slows attackers.

Why filter-repo

git filter-repo is the modern replacement for the deprecated git filter-branch. It is dramatically faster — sometimes 100x — safer by default, and provides the high-level operations history surgery actually needs: removing files, renaming paths, stripping authors, splitting subdirectories, and changing email addresses across all commits.

The subtree model

A subtree merges another repository's history into a subdirectory of yours. Unlike submodules, there is no separate gitlink and no extra commands required for clone — anyone who clones your repo gets the subtree contents automatically. The cost is a fatter history; the benefit is operational simplicity.

The frustration list

Submodules are powerful but trip new users repeatedly. This page catalogs the most common failures and the recipes that fix them.

Empty submodule directory

You cloned the parent but the subdir is empty. Initialize and update:

What submodules are

A submodule is a Git repository nested inside another. The parent repo records the submodule's URL and a specific commit SHA, so anyone cloning the parent can fetch the exact code that was tested together. Use submodules when you want to vendor a dependency at a pinned commit while preserving its independent history.

Hands-free bisection

Manual bisect requires a human verdict at each step. git bisect run automates the loop: provide a script that exits 0 for good, non-zero for bad, and 125 for "skip this commit." Bisect will drive the search to completion, often unattended.

The contract

Your script must:

Binary search through history

git bisect performs a binary search across commits to find the one that introduced a bug. Given a known-good and known-bad commit, Git checks out commits in the middle and asks you to test. Each answer halves the search space, so 1024 commits resolve in about 10 steps.

What cherry-pick does

git cherry-pick applies the diff of one or more commits onto the current branch as new commits. It is the right tool when you want a specific change without merging the entire branch — typical for backporting fixes to a release branch or pulling a hotfix forward.

Why interactive rebase

Interactive rebase rewrites a sequence of commits into a cleaner, more meaningful history before publishing. It is the surgical instrument of Git: you can reorder, edit, squash, fixup, drop, reword, or split commits, all in a single guided session. Mastering it transforms a messy local branch into a story reviewers can follow.

The todo list

Running git rebase -i opens an editor with a todo list. Each line has a verb and a commit. Reorder lines to reorder commits. Change verbs to change behavior.