Overview

git init creates the .git/ directory that turns a plain folder into a repository, starting from zero commits. git clone instead copies an EXISTING repository's entire object database and history, then checks out a working tree -- it never starts from empty.

The working tree (what you edit on disk), the staging area / index (what the next commit will contain), and committed history (permanent, content-addressed snapshots).

Blob (raw file content), tree (a directory listing: modes, types, hashes, names), commit (a snapshot pointer plus metadata: tree hash, parent(s), author, committer, message), and tag (an optional, richer wrapper around a commit with its own tagger/message).

A branch is just a named pointer to one commit -- nothing more. HEAD normally points at the current branch (which then points at a commit), a two-step indirection; in a "detached HEAD" state, HEAD points straight at a commit instead, with no branch in between.

git add copies a file's current content from the working tree into the index. git status reports each file as untracked, modified-but-unstaged, or staged ("Changes to be committed").

-p walks through a file's changes one hunk at a time, asking whether to stage each one individually -- and s can split one hunk into smaller sub-hunks. This lets one physical editing session become several separately-stageable, separately-committable pieces, instead of forcing the whole file into one commit.

It records whatever is currently staged as a new, permanent commit. The convention is a short imperative- mood subject line, optionally followed by a blank line and a longer explanatory body.

It does not edit the old commit in place -- Git objects are immutable. It creates a brand-new commit (same or updated content/message) and moves the branch pointer to it, leaving the old commit unreferenced (recoverable via reflog for a while).

Working-tree-vs-index (plain git diff), index-vs-HEAD (git diff --staged), and any two arbitrary commits or branches (git diff A B, or the two-dot/three-dot branch-comparison forms).

Any three of: git log --oneline (compact one-line-per-commit), git log --graph --all (ASCII commit graph across every branch), git log --pretty=format:"..." (custom per-commit template), git show <commit> (metadata plus diff for one commit), git cat-file -p/-t <hash> (an object's raw content or type, directly from storage).

git switch -c <name> (equivalent to the older git checkout -b <name>) -- combines git branch <name> and git switch <name> into one step.

When the target (receiving) branch has not diverged at all since the merged-in branch was created -- Git simply slides the target branch's pointer forward to match the other branch's tip, with no new commit and no reconciliation needed.

"Three-way" refers to the three trees compared: the common ancestor and both branch tips. The resulting merge commit has TWO parent lines in its raw object -- the unambiguous, low-level proof, visible via git cat-file -p.

Both sides changing the exact same content in incompatible ways. Resolution: edit the file to remove the <<<<<<</=======/>>>>>>> markers with the actually-intended content, git add the resolved file, then git commit (or --continue for a rebase/cherry-pick) -- or --abort to cancel entirely.

Rebase REPLAYS a branch's commits, one at a time, onto a new base -- each replayed commit gets a brand-new hash (its parent, and therefore its content-hash, genuinely changed), producing a single linear history instead of a fork-and-rejoin shape.

reword (change one commit's message only), squash (fold a commit into the one above it), reordering (swap todo-list lines to change replay order), and drop (skip replaying a commit entirely).

Rebase local work (commits nobody else has pulled yet); merge shared work (commits already pushed and pulled by someone else) -- never rebase history others have already pulled, because rebase rewrites commit identity and breaks their next push/pull.

--soft moves only HEAD (index and working tree untouched -- the undone commit's change reappears staged). --mixed (the default) moves HEAD and resets the index, but leaves the working tree's file content untouched. --hard moves HEAD, the index, AND forces the working tree to match -- the only mode that can discard uncommitted-equivalent content.

revert creates a brand-new commit whose diff is the exact inverse of a target commit -- additive; the original commit stays fully intact in history. reset --hard instead moves the branch pointer backward, removing commits from the branch's reachable history entirely (though not immediately from storage).

Plain git restore <file> defaults its source to HEAD, discarding an uncommitted working-tree edit by copying HEAD's version back in. --source=<commit> picks a different baseline, restoring that file's content from any other commit's tree, with no effect on HEAD or history.

It shelves the current index+working-tree state onto a stack and restores the working tree to match HEAD. pop reapplies the most recent entry AND removes it from the stack; apply reapplies it but leaves a copy on the stack (useful for applying the same stash to more than one branch).

It records every position HEAD has ever occupied, locally, per-repository -- entirely separate from the commit graph git log shows. It only remembers COMMITS HEAD pointed to, never uncommitted working-tree edits.

git fetch downloads new objects and updates remote-tracking refs (origin/main), never touching local branches or the working tree. git push uploads local commits the remote lacks and moves the remote's own ref to match -- rejected if the local branch is behind the remote's current tip (non-fast-forward).

A remote-tracking ref (like origin/feature) is a local bookmark for "where a branch last looked on that remote." git push -u origin <branch> pushes AND establishes that the local branch tracks the matching remote ref, so future plain push/pull know the default target with no branch name needed.

A lightweight tag (git tag <name>) is just a ref pointing straight at a commit -- no extra object. An annotated tag (git tag -a <name> -m "...") creates a genuine tag OBJECT with its own tagger, date, and message, distinct from the commit it points at (git cat-file -t reports "tag", not "commit").

Nothing -- .gitignore only affects UNTRACKED files; an already-tracked file keeps showing up in git status until explicitly untracked with git rm --cached. git add -f <file> force-stages one ignored file as a deliberate, one-time exception.

Plain executable scripts under .git/hooks/ (e.g. pre-commit), run automatically at the lifecycle point their filename names. A nonzero exit code from the hook aborts the commit entirely; exit 0 lets it proceed.

Short-lived branches, integrated to trunk through frequent review (pull request) and merge -- ideally one focused, reviewable change per branch, landed almost immediately rather than accumulating drift from trunk.

It applies the change introduced by one specific commit onto the current branch as a NEW commit -- same author, message, and content diff as the original, but typically a different hash (because its parent usually differs).

git add -p (co-06), stepping through hunks and choosing y/n per hunk. The risk: if the two edits are close enough to fall inside Git's default 3-line diff context, they merge into ONE combined hunk instead of two -- pressing s (split) inside add -p is the fix for that specific case.

--amend (co-08) creates a brand-new commit hash for what looks like "the same" change. Their next git push (or pull) will not recognize the new hash as a continuation of the old one -- Git sees the local and remote histories as having diverged (co-17's warning applies to amend exactly as much as to rebase, since amend is a one-commit rebase).

Succeeds automatically as a genuine three-way merge (co-13) -- Git combines both trees into one new commit with two parents, no conflict, because the two changes touch different parts of the file.

git revert (co-19) -- adds a new, inverse commit, never rewriting anything already shared. Avoid git reset --hard followed by a force-push -- that rewrites history everyone else already has, exactly the scenario co-17's discipline warns against.

git rebase -i (co-16), marking the later commits squash (folding them into the first) and then reword if the combined message needs cleanup -- safe here specifically because the branch is local and unshared (co-17).

git reflog (co-22) to find the hash HEAD pointed to right before the reset (HEAD@{1}), then git reset --hard HEAD@{1} (or git branch <name> <hash> if only one commit, not the whole branch tip, is needed) to restore it.

No -- git rm --cached (co-26) removes a file from the INDEX/tracking only; the --cached flag specifically means "leave the working-tree copy alone." Existing checkouts keep their local file untouched; only future tracking of NEW changes to it stops.

Either the file is not executable (chmod +x was never run, co-27), or the script's own logic exits 0 regardless of what it finds (a bug in the check itself, not in Git's hook mechanism) -- Git only enforces "nonzero exit blocks the commit"; it never inspects what the script's logic actually does.

git cherry-pick <hash> (co-29) on release-1.2, naming just that one commit's hash -- replays only that commit's diff, as a new commit, with no dependency on the rest of develop's history.

No -- git fetch (co-23) deliberately never touches local branches, only remote-tracking refs (origin/main). git log origin/main --oneline would show the new commits; git pull (fetch + merge/ rebase) or an explicit git merge origin/main is what would move local main itself.

Annotated (git tag -a v2.0.0 -m "...", co-25) -- it creates a genuine tag object carrying tagger name, date, and message; a lightweight tag is a bare pointer with no such metadata to read back.

No -- a fast-forward merge (co-12) leaves no trace that a separate branch ever existed; the commits simply appear as a linear continuation of main. If preserving that visibility matters, git merge --no-ff (co-13) is the alternative that forces a real merge commit even when a fast-forward was possible.

Git creates an ordinary commit ON TOP of the detached-HEAD state the rebase left you in -- it does NOT automatically resume replaying the rebase's remaining commits. git rebase --continue is a distinct, required step; a plain commit alone leaves the rebase incomplete and any later original commits unreplayed.

Developer B's push is REJECTED (non-fast-forward, co-23) -- their local branch does not contain Developer A's already-pushed commit, so pushing would silently discard it. This is a deliberate safety check, the exact same principle a local fast-forward-only merge enforces (co-12), applied to the remote.

Fix section

git rm --cached -q config.local
git commit -q -m "stop tracking config.local"
echo "secret=789" > config.local           # => edit again
git status                                  # => FIXED: config.local no longer appears at all -- now
                                            #    genuinely untracked AND ignored, exactly as .gitignore intended
cat config.local                             # => the file itself is untouched on disk the whole time

Root cause: .gitignore patterns are consulted only when deciding whether to WARN about or ADD an untracked file -- Git never re-checks an already-tracked path against .gitignore on every status call. git rm --cached is the required extra step: it removes the path from the index (stops tracking future changes) while --cached specifically leaves the working-tree copy on disk untouched.

Output (real, captured):

=== BUGGY: add the ignore pattern AFTER the file is already tracked ===
On branch main
Changes not staged for commit:
 modified:   config.local
 
no changes added to commit (use "git add" and/or "git commit -a")
=== FIX: git rm --cached removes it from tracking WITHOUT deleting it from disk ===
On branch main
nothing to commit, working tree clean
secret=789

Fix section

git branch rescued "$DETACHED_TIP"            # => recreates a real, permanent pointer at that commit,
                                              #    using the hash noted before switching away (co-11)
git log --oneline rescued | { grep -c "hotfix work" || true; }   # => FIXED: 1 -- reachable again, permanently, via
                                              #    a real branch instead of a soon-to-expire reflog entry

Root cause: Git commits made while HEAD is detached are perfectly real objects, but with no branch pointer keeping them reachable, they become effectively invisible (and eventually garbage-collectible) the moment HEAD moves elsewhere. Noting the tip hash BEFORE switching away, then creating a real branch at that hash, is the fix -- the same principle Example 63's deleted-branch recovery relies on.

Output (real, captured):

=== BUGGY: checking out a commit hash directly, not a branch ===
HEAD detached at 9fb8998
nothing to commit, working tree clean
0
=== FIX: create a branch BEFORE committing in detached HEAD, or immediately after ===
1

Fix section

echo "hours of uncommitted work, take two" > file.txt
git stash push -q -m "safety stash before risky reset"   # => co-21: now genuinely recoverable
git reset --hard HEAD -q                                   # => safe now -- nothing uncommitted to lose
git stash pop -q                                             # => FIXED: the work returns, because it was
                                                              #    shelved onto the stash stack BEFORE the
                                                              #    reset, not left exposed as a plain edit
cat file.txt

Root cause: git reflog records HEAD's history of COMMITS -- it has nothing to say about content that was never committed at all. The only real defenses against reset --hard before uncommitted work is safe are: commit it (even to a throwaway branch), or git stash it first, so it lives somewhere the reset cannot reach.

Output (real, captured):

=== BUGGY: muscle-memory reset --hard when meaning to just discard ONE edit ===
base
dec4f53 HEAD@{0}: reset: moving to HEAD
dec4f53 HEAD@{1}: commit (initial): initial
=== FIX: commit or stash BEFORE any --hard operation, as a safety habit ===
hours of uncommitted work, take two

Fix section

git reset --soft HEAD~1 -q                            # => co-18: undo the risky amend, keep the edit staged
git commit -q -m "shared: work everyone will pull"     # => restore the ORIGINAL message/content as a
                                                        #    fresh commit on top -- do NOT reuse --amend here
echo "additional fix, as a NEW commit" >> file.txt
git commit -aq -m "fix: address feedback in a new commit, not a rewrite"
git push origin main                                     # => FIXED: succeeds -- history only ever grew
                                                        #    forward, nothing shared was ever rewritten

Root cause: this is co-17's central discipline, made concrete: rewriting (amend, rebase, or a history-rewriting filter) is only safe on commits nobody else has pulled yet. Once shared, the fix for "I need to change this" is always a NEW commit on top, never a rewrite of the old one.

Output (real, captured -- the scratch-directory path below is this run's actual mktemp -d result and, like the commit hashes, differs on a different run):

=== BUGGY: rebasing the ALREADY-PUSHED, already-shared commit anyway ===
To /var/folders/fr/jg3jv_4d39b48cyqlqz18mgr0000gn/T/tmp.SGjH1j3x57/remote.git
 ! [rejected]        main -> main (non-fast-forward)
error: failed to push some refs to '/var/folders/fr/jg3jv_4d39b48cyqlqz18mgr0000gn/T/tmp.SGjH1j3x57/remote.git'
hint: Updates were rejected because the tip of your current branch is behind
hint: its remote counterpart. Integrate the remote changes (e.g.
hint: 'git pull ...') before pushing again.
=== FIX: never rewrite a commit that has already been pushed and pulled -- add a NEW commit instead ===
To /var/folders/fr/jg3jv_4d39b48cyqlqz18mgr0000gn/T/tmp.SGjH1j3x57/remote.git
   f83d7c1..86e9989  main -> main

Fix section

cat > file.txt <<'RESOLVED'
combined: main version + feature version
RESOLVED
git add file.txt
git commit --amend --no-edit -q                       # => co-08: amend the just-made bad merge commit --
                                                       #    only safe because it has not been pushed yet
grep -c "<<<<<<<" file.txt || true                     # => FIXED: no markers anywhere in the resolved file

Root cause: git add is a pure "stage this content" operation -- it has no idea what a conflict marker looks like and will happily stage one. The discipline is to always search the file for leftover markers (or use a diff/editor view) BEFORE staging a conflict resolution, never just trust that resolving "felt" complete.

Output (real, captured):

=== BUGGY: git add the conflicted file WITHOUT actually editing out the markers ===
1
1
=== FIX: always search for leftover markers BEFORE staging a conflict resolution ===
0

Fix section

sed -i.bak '/<<<<<<<\|=======\|>>>>>>>/d' file.txt && rm -f file.txt.bak  # => remove markers, keep both real lines
git add file.txt
git stash drop -q                                          # => FIXED: conflict resolved by hand, exactly
                                                             #    like a merge conflict; the stash entry
                                                             #    itself (already merged in) is now redundant
git stash list                                                # => empty -- nothing left shelved

Root cause: git stash pop internally performs a merge between the stashed state and the current working tree -- if both touch the same content, it conflicts exactly like git merge would (co-14), right down to the same conflict-marker resolution loop. A habit of git stash list before editing (to remember what is shelved) avoids the surprise; when it does happen, resolving is identical to any other conflict.

Output (real, captured):

=== BUGGY: forgetting a stash exists, making an UNRELATED edit to the same file, then popping ===
error: Your local changes to the following files would be overwritten by merge:
 file.txt
Please commit your changes or stash them before you merge.
Aborting
The stash entry is kept in case you need it again.
=== FIX: git stash list BEFORE editing, or resolve the conflict like any other (co-14) ===
base
a different, newer edit

Fix section

git push origin --tags                                 # => FIXED: uploads every local tag the remote lacks
git -C ../remote.git tag                                 # => v1.0 now genuinely exists on the remote

Root cause: commits and tags are pushed independently -- git push alone only ever moves branch refs. --tags (or naming the specific tag) is a required, separate upload step, easy to forget the first time a release is cut.

Output (real, captured):

=== BUGGY: tag the release, push main, but forget --tags ===
=== FIX: git push --tags (or push the specific tag by name) ===
To ../remote.git
 * [new tag]         v1.0 -> v1.0
v1.0

Verification section

git diff main~1 main -- fix.txt                            # => empty -- the merge itself introduces NO
                                                         #    further change to fix.txt; its content was
                                                         #    already identical on both sides, so the merged
                                                         #    tree is correct either way, just with two
                                                         #    commit objects recording the same change instead of one

Root cause / why it is not a real bug: git cherry-pick (co-29) always creates a NEW commit -- it never removes or rewrites the original one still sitting on its source branch. When that source branch is later merged normally, both commits remain reachable, and git merge's content-aware algorithm correctly detects that the fix's content is already present, so the merged tree ends up correct with no conflict. The only cost is a slightly noisier git log --graph -- the same fix genuinely appears twice, as two different, permanent commit objects with identical diffs.

Output (real, captured):

=== RISKY: cherry-pick the urgent fix onto main immediately (co-29) ===
cf7e15e urgent bugfix needed on main now
178227b main: unrelated progress
9eb1a65 initial
=== LATER: feature is fully done and gets merged normally ===
*   0a80439 Merge branch 'feature'
|\
| * 42d9fc7 unrelated feature work
| * db3c567 urgent bugfix needed on main now
* | cf7e15e urgent bugfix needed on main now
* | 178227b main: unrelated progress
|/
* 9eb1a65 initial
=== WHY THIS IS SAFE, NOT A CONFLICT: Git's merge machinery still gets it right ===

A commit is the unit of both history AND review -- one commit should represent one cohesive change, so a reviewer (or a future git log -- path, or a git revert) can reason about it in isolation. When two unrelated edits land in the same file during one sitting, committing the whole file couples them into one commit whether they belong together or not. Hunk staging is what lets the commit boundary track the LOGICAL boundary of the change instead of the accidental boundary of "what happened to be open in the editor at the same time."

Merge is honest and safe -- it never rewrites existing commits, at the cost of a fork-and-rejoin shape in history. Rebase produces a cleaner, linear history, at the cost of rewriting commit identity. Neither is strictly "more correct" -- the disciplined compromise (co-17) is contextual: rebase local, still-private work for a clean history before it is ever shared, then merge once it IS shared, because rewriting shared history breaks other people's copies. Teaching only one would either sacrifice history clarity or safety unnecessarily.

Coupling-vs-cohesion is about commit BOUNDARIES matching logical change boundaries, not about each unit of content appearing exactly once in a graph. Each of the two commits is still individually cohesive (one records "the urgent fix", replayed onto main; the other records the identical fix as part of feature's own original history) -- what matters for correctness is that the resulting TREE is right, which Git's merge algorithm verifies directly. The minor cost is graph noise, not incorrectness or coupling.

Silently overwriting would be pragmatic in the narrow sense of "the push always succeeds", but it would also silently discard another developer's already-shared commit with no warning -- a correctness failure disguised as convenience. Git's rejection forces the pusher to explicitly reconcile (pull, merge or rebase, then push again) before their view of history can become the shared one -- the safe default, even though it occasionally means an extra step for the pusher.

A short-lived branch is naturally scoped to one focused change -- there is not enough time for unrelated work to accumulate on it before it merges. A long-lived branch, by contrast, tends to accrete multiple loosely related changes simply because it stays open, which is exactly the coupling this topic's big idea warns against: a branch (and the PR reviewing it) should represent one cohesive unit of change, and branch lifetime is one of the simplest practical levers for enforcing that.

"Be careful" is not a reliable safety mechanism -- muscle memory and mistakes happen regardless of intent, which is precisely what Kata 3 demonstrates. The pragmatic fix is structural, not attitudinal: make the risky window as small as possible by committing or stashing frequently, so there is rarely anything valuable sitting ONLY in the uncommitted working tree when a --hard operation (intentional or not) runs. This trades a small amount of extra typing for removing an entire class of unrecoverable mistakes.