mapas-mentales/mindmap/Git Tools.md

Git Tools

Purpose / Context

• You already know day-to-day Git workflows
  • track + commit files
  • staging area
  • topic branching + merging
• This chapter: powerful/advanced tools you might not use every day, but will eventually need

Revision Selection

• Git can refer to:
  • a single commit
  • a set of commits
  • a range of commits
• References can be:
  • hashes (full/short)
  • branch names
  • reflog entries
  • ancestry expressions
  • range expressions

Single Revisions

• Full SHA-1
  • 40-character commit hash (e.g., from git log)
• Short SHA-1 (abbreviated hash)
  • Git accepts a prefix of the SHA-1 if:
    • at least 4 characters
    • unambiguous among all objects in the object database
  • Inspect a commit (examples; any unique prefix works)
    • git show <full_sha>
    • git show <shorter_unique_prefix>
  • Generate abbreviated commits in log output
    • git log --abbrev-commit --pretty=oneline
    • defaults to 7 characters; lengthens as needed to remain unique
  • Practical uniqueness
    • often 8–10 chars enough within a repo
    • example note: very large repos still have unique prefixes (Linux kernel cited)
• Note: SHA-1 collision concerns (and Git’s direction)
  • SHA-1 digest: 20 bytes / 160 bits
  • Random collisions are astronomically unlikely
    • 50% collision probability requires about 2^80 randomly-hashed objects
    • probability formula cited: p = (n(n-1)/2) * (1/2^160)
  • If a collision happened organically:
    • Git would reuse the first object with that hash (you’d always get first object’s data)
  • Deliberate, synthesized collisions are possible (e.g., shattered.io, Feb 2017)
  • Git is moving toward SHA-256 as the default hash algorithm
    • more resilient to collision attacks
    • mitigation code exists, but cannot fully eliminate attacks
• Branch References
  • If a commit is the tip of a branch, you can refer to it by branch name
    • git show <branch>
    • equivalent to git show <sha_of_branch_tip>
  • Plumbing tool to resolve refs → SHA-1: git rev-parse
    • example: git rev-parse topic1
    • purpose: lower-level operations (not typical day-to-day), but useful for “what is this ref really?”
• Reflog Shortnames
  • Git records a reflog (local history of where HEAD/refs have pointed)
  • View reflog
    • git reflog
    • shows entries like HEAD@{0}, HEAD@{1}, …
  • Refer to older values
    • git show HEAD@{5} (the 5th prior HEAD value in reflog)
  • Time-based reflog syntax
    • git show master@{yesterday}
  • Log-format reflog output
    • git log -g <branch> (e.g., git log -g master)
  • Important properties / limitations
    • reflog is strictly local
      • not shared; differs from other clones
      • freshly cloned repo starts with empty reflog (no local activity yet)
    • retention is limited (typically a few months)
    • time lookups only work while data remains in reflog
  • Mental model
    • reflog ≈ “shell history” for Git refs (personal/session-local)
  • PowerShell gotcha: escaping braces { }
    • git show HEAD@{0} (won’t work)
    • git show HEAD@{0} (OK)
    • git show "HEAD@{0}" (OK)
• Ancestry References
  • Caret ^ (parent selection)
    • ref^ = parent of ref
      • example: HEAD^ = parent of HEAD
    • Windows cmd.exe gotcha: escaping ^
      • git show "HEAD^" or git show HEAD^^
  • Selecting merge parents
    • ref^2 = second parent (merge commits only)
      • first parent: branch you were on when merging (often master)
      • second parent: branch being merged in (topic branch)
  • Tilde ~ (first-parent traversal)
    • ref~ ≡ ref^ (first parent)
    • ref~2 = first-parent-of-first-parent (grandparent)
    • repeated tildes: HEAD~~~ ≡ HEAD~3
  • Combining ancestry operators
    • example: HEAD~3^2 = second parent of the commit found via HEAD~3 (if that commit is a merge)

Commit Ranges

• Motivation / questions answered
  • “What work is on this branch that hasn’t been merged into main?”
  • “What am I about to push?”
  • “What’s unique between two lines of development?”

Double Dot (A..B)

• Meaning
  • commits reachable from B but not reachable from A
• Example uses
  • “what’s in experiment not in master?”
    • git log master..experiment
  • opposite direction (what’s in master not in experiment)
    • git log experiment..master
  • “what am I about to push?”
    • git log origin/master..HEAD
• Omitted side defaults to HEAD
  • git log origin/master.. ≡ git log origin/master..HEAD

Multiple Points (^ / --not)

• Double-dot is shorthand for a common two-point case
• Equivalent forms
  • git log refA..refB
  • git log ^refA refB
  • git log refB --not refA
• Advantage: can exclude multiple refs
  • “reachable from refA or refB, but not from refC”
    • git log refA refB ^refC
    • git log refA refB --not refC

Triple Dot (A...B)

• Meaning (symmetric difference)
  • commits reachable from either A or B but not both
• Example
  • git log master...experiment
• Often paired with --left-right
  • git log --left-right master...experiment
  • marks which side each commit is from (< vs >)

Interactive Staging

• Goal
  • craft commits that contain only certain combinations/parts of changes
  • split large messy changes into focused, reviewable commits

Interactive add mode

• Start
  • git add -i / git add --interactive
• What it shows
  • staged vs unstaged changes per path (like git status, but compact)
• Core commands menu (as shown)
  • s status
  • u update (stage files)
  • r revert (unstage files)
  • a add untracked
  • p patch (stage hunks)
  • d diff (review staged diff)
  • q quit
  • h help

Staging and unstaging files (interactive)

• Stage files
  • u / update
  • select by numbers (comma-separated)
  • * indicates selected items
  • press Enter with nothing selected to stage all selected
• Unstage files
  • r / revert
  • select paths to remove from index
• Review staged diff
  • d / diff
  • select file(s) to see
  • comparable to git diff --cached

Staging patches (partial-file staging)

• Enter patch selection
  • from interactive prompt: p / patch
  • from command line: git add -p / git add --patch
• Git presents hunks and asks whether to stage each
• Hunk prompt options (as listed)
  • y stage this hunk
  • n do not stage this hunk
  • a stage this and all remaining hunks in file
  • d do not stage this hunk nor any remaining hunks in file
  • g select a hunk to go to
  • / search for a hunk matching a regex
  • j leave this hunk undecided, go to next undecided hunk
  • J leave this hunk undecided, go to next hunk
  • k leave this hunk undecided, go to previous undecided hunk
  • K leave this hunk undecided, go to previous hunk
  • s split current hunk into smaller hunks
  • e manually edit the current hunk
  • ? help
• Result
  • a file can be partially staged (some staged, some unstaged)
  • exit and git commit will commit staged parts only
• Patch mode appears in other commands too
  • git reset --patch (partial unstage/reset)
  • git checkout --patch (partial checkout/revert)
  • git stash save --patch (stash parts; mentioned as further detail later)

Stashing and Cleaning

Stash: why and what it does

• Problem
  • need to switch branches while work is half-done
  • don’t want to commit unfinished work
• git stash saves:
  • modified tracked files (working directory)
  • staged changes (index)
• Stores changes on a stack; can reapply later (even on different branch)
• Note: migration to git stash push
  • git stash save discussed as being deprecated in favor of git stash push
  • key reason: push supports stashing selected pathspecs

Stashing your work (basic flow)

• Observe dirty state
  • git status shows staged + unstaged changes
• Create stash
  • git stash or git stash push
  • working directory becomes clean
• List stashes
  • git stash list (e.g., stash@{0}, stash@{1}, …)
• Apply stash
  • most recent: git stash apply
  • specific: git stash apply stash@{2}
  • can apply on different branch
  • conflicts possible if changes don’t apply cleanly
• Restore staged state too
  • git stash apply --index
• Remove stashes
  • drop by name: git stash drop stash@{0}
  • apply + drop: git stash pop

Creative stashing (useful options)

• Keep staged changes in index
  • git stash --keep-index
  • stashes everything else, but leaves index intact
• Include untracked files
  • git stash -u / git stash --include-untracked
• Include ignored files too
  • git stash --all / git stash -a
• Patch stashing (stash some hunks, keep others)
  • git stash --patch
  • interactive hunk selection (prompt options include y/n/q/a/d//e/? per stash prompt)

Create a branch from a stash

• Use case
  • stash is old; applying on current branch causes conflicts
• Command
  • git stash branch <new-branchname>
• Behavior
  • creates a new branch at the commit you were on when stashing
  • checks it out
  • reapplies stash there
  • drops stash if it applies successfully

Cleaning your working directory (git clean)

• Purpose
  • remove untracked files/dirs (“cruft”)
  • remove build artifacts for clean build
• Caution
  • removes files not tracked by Git
  • often no way to recover
  • safer alternative when unsure: git stash --all
• Common usage
  • preview only: git clean -n / git clean --dry-run
  • remove untracked files + empty dirs:
    • git clean -f -d
    • -f required unless clean.requireForce=false
• Ignored files
  • default: ignored files are NOT removed
  • remove ignored too: git clean -x
• Interactive cleaning
  • git clean -x -i
  • interactive commands shown:
    • clean
    • filter by pattern
    • select by numbers
    • ask each
    • quit
    • help
• Quirk (nested Git repos)
  • directories containing other Git repos may require extra force
  • may need a second -f (e.g., git clean -ffd)

Signing Your Work (GPG)

• Git is cryptographically secure (hashing), but not foolproof for trust
• When consuming work from others, signing helps verify authorship/integrity

GPG setup

• List keys: gpg --list-keys
• Generate key: gpg --gen-key
• Configure Git signing key
  • git config --global user.signingkey <KEYID>

Signing tags

• Create signed tag
  • git tag -s <tag> -m '<message>' (instead of -a)
• View signature
  • git show <tag>
• Passphrase may be required to unlock key

Verifying tags

• Verify signed tag
  • git tag -v <tag-name>
• Requires signer’s public key in your keyring
  • otherwise: “public key not found” / cannot verify

Signing commits

• Sign a commit (Git v1.7.9+)
  • git commit -S ...
• View/check signatures
  • git log --show-signature -1
  • signature status in custom format: git log --pretty="format:%h %G? %aN %s"
    • example statuses shown in chapter:
      • G = good/valid signature
      • N = no signature

Enforcing signatures in merges/pulls (Git v1.8.3+)

• Verify signatures during merge/pull
  • git merge --verify-signatures <branch>
  • merge fails if commits are unsigned/untrusted
• Verify + sign resulting merge commit
  • git merge --verify-signatures -S <branch>

Workflow consideration: everyone must sign

• If you require signing:
  • ensure all contributors know how to do it
  • otherwise you’ll spend time helping rewrite commits to signed versions
• Understand GPG + benefits before adopting as standard workflow

Searching

git grep (search code)

• Search targets
  • working directory (default)
  • committed trees
  • index (staging area)
• Useful options
  • line numbers: -n / --line-number
  • per-file match counts: -c / --count
  • show enclosing function: -p / --show-function
• Complex queries
  • combine expressions on same line with --and
  • multiple -e <pattern> expressions
  • can search historical trees (example in chapter uses tag v1.8.0)
  • output readability helpers: --break, --heading
• Advantages vs external tools (grep/ack)
  • very fast
  • can search any Git tree, not just current checkout

git log searching (by content)

• Find when a string was introduced/changed (diff-based search)
• Pickaxe (-S)
  • git log -S <string>
  • shows commits that changed number of occurrences of the string
• Regex diff search (-G)
  • git log -G <regex>

Line history search (git log -L)

• Show history of a function/line range as patches
• Function syntax
  • git log -L :<function_name>:<file>
• Regex/range alternatives if function parsing fails
  • regex + end pattern: git log -L '/<regex>/',/^}/:<file>
  • explicit line ranges or a single line number also supported (noted)

Rewriting History

Why rewrite history (locally)

• Make history reflect logical, reviewable changes
  • reorder commits
  • rewrite messages
  • modify commit contents
  • squash/split commits
  • remove commits entirely
• Cardinal rule
  • don’t push until you’re happy
  • rewriting pushed history confuses collaborators (treat pushed as final unless strong reason)

Changing the last commit

• Amend message and/or content
  • git commit --amend
• Common patterns
  • fix message only: amend, edit message in editor
  • fix content:
    • edit files → stage changes → git commit --amend
• Caution
  • amending changes SHA-1 (like small rebase)
  • don’t amend a commit that’s already pushed
• Tip: avoid editor if message unchanged
  • git commit --amend --no-edit
• Note: commit message may need updating if content changes substantially

Changing multiple commit messages (interactive rebase)

• Tool: interactive rebase
  • git rebase -i <upstream>
• Choosing the range
  • specify the parent of the oldest commit you want to edit
  • example for last 3 commits: git rebase -i HEAD~3
• Warning
  • rewrites every commit in selected range and descendants
  • avoid rewriting commits already pushed
• Interactive todo list properties
  • commits listed oldest→newest (reverse of typical git log output)
  • Git replays commits top→bottom
• Todo commands shown
  • pick use commit
  • reword use commit, edit message
  • edit stop for amending
  • squash meld into previous, edit combined message
  • fixup like squash, discard this commit message
  • exec run shell command
  • break stop here, continue later with git rebase --continue
  • drop remove commit
  • label label current HEAD
  • reset reset HEAD to a label
  • merge create merge commit (with options to keep/reword message)
  • notes shown in template:
    • lines can be re-ordered
    • removing a line loses that commit
    • removing everything aborts rebase
    • empty commits commented out

Reordering commits (interactive rebase)

• Reorder lines in todo file
• Save + exit
  • Git rewinds branch to parent of the todo range
  • replays commits in new order

Removing commits (interactive rebase)

• Delete the line or mark it drop
• Effects
  • rewriting a commit rewrites all following commits’ SHA-1s
  • can cause conflicts if later commits depend on removed one

Squashing commits

• Mark subsequent commits as squash (or fixup)
• Git:
  • applies changes together
  • opens editor to combine messages (except fixup discards message)
• Outcome
  • a single commit replacing multiple commits

Splitting a commit

• Mark target commit as edit in rebase todo
• When rebase stops at that commit
  • undo that commit while keeping changes in working tree/index state
    • git reset HEAD^ (mixed reset)
  • stage and commit portions into multiple commits
  • continue rebase
    • git rebase --continue
• Reminder
  • rewriting changes SHA-1s of affected commit and subsequent commits
  • avoid if any are pushed

Aborting or recovering

• Abort in-progress rebase
  • git rebase --abort
• After completing, recover earlier state
  • use reflog (chapter references this as Data Recovery elsewhere)

The nuclear option: filter-branch

• Purpose
  • scriptable rewriting across many commits
  • examples:
    • remove file from every commit
    • change email globally
    • rewrite project root from subdirectory
• Warning callout
  • git filter-branch has many pitfalls; no longer recommended
  • prefer git-filter-repo (Python) for most use cases
• Common uses shown
  • Remove a file from every commit (e.g., secrets/huge binaries)
    • git filter-branch --tree-filter 'rm -f passwords.txt' HEAD
    • --tree-filter runs command after each checkout; recommits results
    • can use patterns (e.g., rm -f *~)
    • to run across all branches: --all
    • recommended: test in a branch, then hard-reset master if satisfied
  • Make a subdirectory the new root
    • git filter-branch --subdirectory-filter trunk HEAD
    • auto-removes commits that didn’t affect the subdirectory
  • Change email addresses globally (only yours)
    • git filter-branch --commit-filter '<script>' HEAD
    • script checks GIT_AUTHOR_EMAIL, rewrites author name/email, calls git commit-tree
    • note: parent SHA-1 changes propagate, rewriting entire history chain

Reset Demystified (reset & checkout mental model)

The Three Trees (collections of files)

• HEAD
  • last commit snapshot; next parent
  • pointer to current branch ref → last commit on that branch
  • inspect snapshot (plumbing examples shown)
    • git cat-file -p HEAD
    • git ls-tree -r HEAD
• Index (staging area)
  • proposed next commit snapshot (what git commit uses)
  • inspect index (plumbing)
    • git ls-files -s
  • note: implemented as flattened manifest (not a literal tree), but treated as “tree” conceptually
• Working Directory
  • sandbox with real files (editable)
  • unpacked from .git storage into filesystem

Typical workflow across the three trees

• After git init
  • only working directory has content
• git add
  • copies content working directory → index
• git commit
  • writes index snapshot → commit
  • moves current branch pointer (HEAD’s branch)
• Clean state
  • HEAD == index == working directory
• Modify file
  • working directory differs from index → “Changes not staged”
• Stage file
  • index differs from HEAD → “Changes to be committed”
• Checkout behavior summary (mentioned)
  • git checkout <branch>:
    • moves HEAD to that branch
    • fills index with commit snapshot
    • copies index → working directory

The role of reset (commit-level)

• Reset manipulates the three trees in order (up to 3 operations)
  1. Move the branch HEAD points to (REF move)
  2. Update index to match new HEAD (--mixed)
  3. Update working directory to match index (--hard)
• Step 1: move HEAD’s branch ref
  • always attempted when reset is given a commit
  • --soft stops here
  • resembles undoing the last git commit (ref moves back)
• Step 2: update index (--mixed, default)
  • index becomes snapshot of new HEAD
  • --mixed stops here
  • resembles undoing git add + git commit
• Step 3: update working directory (--hard)
  • working directory overwritten to match index
  • this is the dangerous form
    • can destroy uncommitted work
    • other forms are generally recoverable (e.g., via reflog)

Reset with a path (file-level)

• Behavior change
  • skips step 1 (can’t move a ref “partially”)
  • applies index/working-dir updates only for specified paths
• Common unstage use
  • git reset file.txt
    • shorthand for git reset --mixed HEAD file.txt
    • copies file from HEAD → index (unstages)
    • conceptual opposite of git add file.txt
• Reset a path to a specific commit’s version (index only)
  • git reset <commit> file.txt
  • can prepare a commit that reverts a file without checking out old version into working dir
• Patch mode
  • git reset --patch allows selective unstaging/resetting hunks

Squashing commits with reset

• Alternative to interactive rebase for simple cases
• Example flow
  • git reset --soft HEAD~2
  • git commit (creates one commit combining last two commits’ changes)

Checkout vs Reset

• Both manipulate the three trees; differences depend on “with paths” or not

Without paths

• git checkout <branch>
  • similar outcome to git reset --hard <branch> (trees match target)
  • key differences
    • working-directory safe
      • checks + trivial merges; avoids overwriting local changes where possible
    • moves HEAD itself to point to another branch
• git reset <branch>
  • moves the branch ref HEAD points to (REF move), not HEAD

With paths

• git checkout [commit] <paths>
  • does not move HEAD
  • updates index and working directory for those paths
  • not working-directory safe (can overwrite local changes)
  • supports --patch for hunk-by-hunk revert

Cheat sheet (which trees each command affects)

• Commit level
  • reset --soft [commit]
    • HEAD column: REF moves; Index: no; Workdir: no; WD safe: yes
  • reset [commit] (default mixed)
    • REF moves; Index: yes; Workdir: no; WD safe: yes
  • reset --hard [commit]
    • REF moves; Index: yes; Workdir: yes; WD safe: NO
  • checkout <commit>
    • HEAD moves; Index: yes; Workdir: yes; WD safe: yes
• File level
  • reset [commit] <paths>
    • HEAD: no; Index: yes; Workdir: no; WD safe: yes
  • checkout [commit] <paths>
    • HEAD: no; Index: yes; Workdir: yes; WD safe: NO

Advanced Merging

Git merge philosophy and practical guidance

• Git often makes merging easy, enabling long-lived branches with frequent merges
  • resolve small conflicts often instead of huge conflicts later
• Git avoids “overly clever” auto-resolution
  • if ambiguous, it stops and asks you to resolve
• Best practice before merges that might conflict
  • start with a clean working directory
  • otherwise commit to temp branch or stash

Merge conflicts: tools and strategies

Aborting a merge

• If you don’t want to deal with conflicts yet
  • git merge --abort
  • returns to pre-merge state (unless WIP changes complicate)
• “Start over” option (dangerous)
  • git reset --hard HEAD (loses uncommitted work)

Ignoring whitespace during merge

• If conflicts are largely whitespace-related
  • re-run merge with strategy options
    • git merge -Xignore-all-space <branch>
    • git merge -Xignore-space-change <branch>
• Practical benefit
  • resolves merges where only formatting/line endings differed

Manual file re-merging (scriptable fixes)

• Use case
  • Git can’t auto-handle some transformations (e.g., normalize line endings)
• Concept
  • extract three versions of the conflicted file from index stages
    • stage 1: base/common ancestor
    • stage 2: ours
    • stage 3: theirs (MERGE_HEAD)
• Extract versions
  • git show :1:<file> > <file>.common
  • git show :2:<file> > <file>.ours
  • git show :3:<file> > <file>.theirs
• Inspect blob SHAs in index
  • git ls-files -u
• Preprocess + merge single file
  • preprocess one side (example shown: dos2unix on theirs)
  • merge with git merge-file -p ours common theirs > <file>
• Compare result vs each side (helpful review)
  • git diff --ours
  • git diff --theirs -b (strip whitespace for Git-stored version comparisons)
  • git diff --base -b
• Cleanup temp artifacts
  • git clean -f

Checking out conflicts / marker styles / choosing sides

• Re-checkout file with conflict markers
  • git checkout --conflict=merge <file> (default style)
  • git checkout --conflict=diff3 <file> (adds inline base section)
• Make diff3 default
  • git config --global merge.conflictstyle diff3
• Quickly choose one side for a file
  • git checkout --ours <file>
  • git checkout --theirs <file>
  • useful for binary files or “take one side” decisions

Merge log (find what contributed to conflicts)

• Show unique commits from both sides of merge
  • git log --oneline --left-right HEAD...MERGE_HEAD
• Show only commits that touch currently conflicted file(s)
  • git log --oneline --left-right --merge
  • add -p to view diffs of the conflicted file(s)

Combined diff format

• During unresolved merge conflicts
  • git diff shows “combined diff” (diff --cc)
  • two columns indicate differences vs ours and vs theirs
• After resolving conflict
  • combined diff highlights:
    • what was removed from ours
    • what was removed from theirs
    • what resolution introduced
• Review after the fact
  • git show <merge_commit> shows combined diff for merge
  • git log --cc -p includes combined diffs in log output

Undoing merges

• Scenario: accidental merge commit

Option 1: fix references (rewrite history)

• If unwanted merge exists only locally
  • git reset --hard HEAD~
• Downside
  • rewrites history (problematic if others have the commits)
  • won’t work safely if other commits happened after the merge (would lose them)

Option 2: reverse the merge commit (revert)

• Create a new commit that undoes changes introduced by merge
  • git revert -m 1 HEAD
• -m 1 (mainline parent selection)
  • keep parent #1 (current branch’s line)
  • undo parent #2’s introduced changes
• Important consequence
  • history still contains original merged commits
  • merging that branch again may say “Already up-to-date”
  • later merges may only bring changes since reverted merge
• Fix when you actually want to re-merge later
  • “un-revert” the revert commit (git revert ^M as shown conceptually)
  • then merge again to bring full changes

Other types of merges

“Ours” / “Theirs” preference (recursive strategy option)

• Use when conflicts should default to one side
  • git merge -Xours <branch>
  • git merge -Xtheirs <branch>
• Behavior
  • still merges non-conflicting changes normally
  • for conflicts, chooses the specified side entirely (including binaries)
• Similar capability at file-merge level
  • git merge-file --ours ... (noted)

“ours” merge strategy (-s ours) (fake merge)

• Different from -Xours
• Command
  • git merge -s ours <branch>
• Behavior
  • records merge commit with both parents
  • result tree equals current branch (ignores merged-in branch content)
• Use case
  • mark work as merged to avoid conflicts later (e.g., backport workflows)

Subtree merging

• Problem solved
  • one project is a subdirectory of another
• Example workflow (shown)
  • add other project as remote; fetch
  • checkout remote branch into local branch (e.g., rack_branch)
  • import that branch into subdirectory of main project
    • git read-tree --prefix=<dir>/ -u <branch>
  • merge upstream changes back into main project subtree
    • git merge --squash -s recursive -Xsubtree=<dir> <branch>
• Notes / tradeoffs (explicitly discussed)
  • avoids submodules; all code in one repo
  • more complex; easier to make reintegration mistakes; risk of pushing unrelated branches
• Diffing subtree vs a branch
  • use git diff-tree -p <branch> (not plain git diff)

Rerere (reuse recorded resolution)

• Meaning: “reuse recorded resolution”
• Value
  • remembers how you resolved a conflict hunk
  • next time the same conflict appears, resolves automatically
• Useful scenarios cited
  • long-lived topic branches: repeated merges without keeping intermediate merge commits
  • frequent rebases: avoid re-resolving same conflicts repeatedly
  • test-merge many evolving branches: redo merges without re-resolving
• Enable rerere
  • git config --global rerere.enabled true
  • (alternative: create .git/rr-cache directory per repo)
• During a conflict with rerere enabled
  • message appears: Recorded preimage for '<file>'
• Inspect rerere data
  • git rerere status (files recorded)
  • git rerere diff (preimage vs resolved state)
• After resolving and committing
  • message: Recorded resolution for '<file>'.
• Reuse in later conflict (merge/rebase)
  • message: Resolved '<file>' using previous resolution.
  • file may already be clean (markers removed)
  • can recreate conflict markers for inspection
    • git checkout --conflict=merge <file>
  • can reapply cached resolution explicitly
    • git rerere

Debugging with Git

File annotation (git blame)

• When you know “where” the bug is, but not “when” it appeared
• Command
  • git blame <file>
  • restrict range with -L <start>,<end>
• Output fields explained
  • short SHA-1 of commit that last modified each line
  • author name + authored date
  • line number + line content
• Special ^ prefix in blame output
  • indicates line originated in initial commit and never changed
• Track code movement/copies
  • git blame -C tries to find where code was copied from
  • can show original file/commit for copied snippets (not just when copied)

Binary search for bug introduction (git bisect)

• Purpose
  • find the first bad commit via binary search
• Basic workflow
  • start: git bisect start
  • mark current as bad: git bisect bad
  • mark last known good: git bisect good <good_commit> (example uses v1.0)
  • Git checks out midpoint; you test; mark good or bad
  • repeat until Git identifies first bad commit
• Output when finished
  • indicates first bad commit SHA-1 + commit info + changed paths
• Clean up
  • git bisect reset (return to original HEAD)
• Automation
  • specify range directly: git bisect start <bad> <good>
  • run script that returns 0 for good, non-0 for bad
    • git bisect run <test-script>

Submodules

Motivation and concept

• Need to use another project inside yours while keeping it separate
• Tradeoffs of alternatives
  • shared library install: hard to customize; deployment complexity
  • copying source: hard to merge upstream changes
• Submodules
  • allow a Git repository as a subdirectory of another
  • superproject records a specific subproject commit

Starting with submodules

• Add submodule
  • git submodule add <url> [path]
  • default path = repo name
• What changes in superproject
  • .gitmodules file created (version-controlled)
    • maps submodule.<name>.path and submodule.<name>.url
  • submodule directory entry staged as a special Git mode
    • mode 160000 (records a commit as a directory entry)
  • diff behavior
    • git diff --cached <submodule> shows “Subproject commit ”
    • nicer: git diff --cached --submodule
• Commit and push as normal (superproject now pins a submodule commit)
• URL accessibility note
  • .gitmodules URL is what others use to clone/fetch
  • choose a URL others can access
  • you can override locally via git config submodule.<name>.url <PRIVATE_URL>
  • relative URLs can help in some setups

Cloning a repo with submodules

• Default clone behavior
  • submodule directories exist but are empty (no files)
• Initialize and update
  • git submodule init
  • git submodule update
• One-step clone
  • git clone --recurse-submodules <url>
• If you already cloned
  • combine init+update: git submodule update --init
  • include nested submodules: git submodule update --init --recursive

Working with submodules

Pulling upstream changes from submodule remote (consumer model)

• Manual inside submodule
  • git fetch
  • git merge origin/<branch>
• Show submodule changes from superproject
  • git diff --submodule
  • set default diff format:
    • git config --global diff.submodule log
• Auto-update from superproject
  • git submodule update --remote [<submodule>]
  • default branch tracked: submodule’s master unless configured otherwise
• Track a different branch (e.g., stable)
  • store for everyone: edit .gitmodules
    • git config -f .gitmodules submodule.<name>.branch stable
  • then git submodule update --remote
• Status improvements
  • git status shows submodule “modified (new commits)”
  • git config status.submodulesummary 1 shows brief summary

Pulling upstream changes from superproject remote (collaborator model)

• git pull
  • fetches superproject commits
  • also fetches submodule objects (as shown)
  • but does NOT update submodule working directories by default
• Symptoms
  • git status shows submodule modified with “new commits”
  • arrows in summary may indicate expected commits not checked out locally
• Fix
  • git submodule update --init --recursive
• Automate
  • git pull --recurse-submodules (Git ≥ 2.14)
  • default recursion for supported commands: git config submodule.recurse true (pull recursion since Git 2.15)
• Special case: upstream changed submodule URL in .gitmodules
  • remedy:
    • git submodule sync --recursive
    • git submodule update --init --recursive

Working on a submodule (active development)

• Detached HEAD default issue
  • git submodule update often leaves submodule in detached HEAD
  • local commits risk being “orphaned” by future updates
• Make it hackable
  • enter submodule and checkout a branch
    • git checkout <branch> (e.g., stable)
• Updating while you have local work
  • merge upstream into your local branch
    • git submodule update --remote --merge
  • or rebase local changes
    • git submodule update --remote --rebase
  • if you forget --merge/--rebase
    • Git updates submodule checkout and may leave you detached again
• Safety behaviors
  • if local changes would be overwritten: update aborts and tells you to commit/stash
  • conflicts during --merge update are resolved inside the submodule like normal merges

Publishing submodule changes

• Problem
  • pushing superproject that references submodule commits not available on any remote breaks others
• Push options
  • check mode (fail if submodules not pushed)
    • git push --recurse-submodules=check
    • default config: git config push.recurseSubmodules check
  • on-demand mode (push submodules first automatically)
    • git push --recurse-submodules=on-demand
    • default config: git config push.recurseSubmodules on-demand

Merging submodule changes (superproject conflicts)

• Fast-forward case
  • if one submodule commit is ancestor of the other, Git chooses the newer (works)
• Divergent case
  • Git does not trivial-merge submodule histories for you
  • conflict example shown: CONFLICT (submodule): Merge conflict in <submodule>
• Diagnose SHAs
  • git diff on the superproject shows both submodule commit IDs
• Manual resolution flow (shown)
  • enter submodule
  • create a branch pointing to the other side’s SHA (e.g., try-merge)
  • merge it, resolve conflicts, commit in submodule
  • return to superproject
  • git add <submodule> to record resolved submodule pointer
  • commit superproject merge
• Alternative case: Git suggests an existing submodule merge commit
  • it may print a “possible merge resolution” SHA and a suggested git update-index --cacheinfo 160000 <sha> <path>
  • recommended approach still: verify in submodule, fast-forward/merge, then git add + commit

Submodule tips

• Run commands in each submodule
  • git submodule foreach '<cmd>'
  • examples shown
    • stash across all: git submodule foreach 'git stash'
    • create branch across all: git submodule foreach 'git checkout -b <branch>'
    • unified diffs: git diff; git submodule foreach 'git diff'
• Useful aliases (examples)
  • sdiff = diff superproject + each submodule diff
  • spush = push with --recurse-submodules=on-demand
  • supdate = submodule update --remote --merge

Issues with submodules

• Switching branches (older Git < 2.13)
  • switching to branch without submodule leaves submodule directory as untracked
  • cleanup needed: git clean -ffdx
  • switching back requires git submodule update --init
• Newer Git (≥ 2.13)
  • git checkout --recurse-submodules <branch> keeps submodules consistent when switching
  • you can default recursion: git config submodule.recurse true
• Switching from subdirectories to submodules
  • if a directory is already tracked, git submodule add fails (“already exists in the index”)
  • fix: git rm -r <dir> first, then git submodule add ...
  • switching back to branch where files are tracked (not submodule) can fail due to untracked files overwrite risk
    • can force with git checkout -f (danger: overwrites unsaved changes)
  • may end with empty submodule directory; may need inside submodule: git checkout .
• Storage note (modern Git)
  • submodule Git data stored in superproject’s .git directory
  • deleting submodule working directory won’t lose commits/branches

Bundling (git bundle)

• Purpose
  • transfer Git data without network protocols (HTTP/SSH)
• Use cases
  • no network
  • offsite/security constraints
  • broken networking hardware
  • email/USB transfer
• Create bundle
  • git bundle create <file.bundle> <ref_or_range>...
  • must list each reference/range to include
  • to be cloneable, include HEAD plus branch (example: HEAD master)
• Clone from bundle
  • git clone <bundle> <dir>
  • if HEAD not included, may need -b <branch> to choose checkout branch
• Incremental bundles (send only new commits)
  • you must compute the range manually (unlike network push)
  • range examples used
    • origin/master..master
    • master ^origin/master
  • create incremental bundle example pattern
    • git bundle create <bundle> master ^<known_base_commit>
• Inspect / validate bundles
  • verify bundle and prerequisites
    • git bundle verify <bundle>
  • list heads
    • git bundle list-heads <bundle>
• Import
  • fetch from bundle to a local branch
    • git fetch <bundle> <bundleBranch>:<localBranch>
  • inspect graph with git log --graph --all

Replace (git replace)

• Core idea
  • Git objects are immutable, but replace lets Git pretend object A is object B
  • “when you refer to X, use Y instead”
• Common use
  • replace a commit without rewriting entire history (vs filter-branch)
  • graft histories together (short “recent” history + longer “historical” history)

Example: grafting history without rewriting all SHA-1s

• Split repository into:
  • historical repo (commits 1→4)
  • truncated recent repo (commits 4→5 + an “instructions” base commit)
• Tools used (as shown)
  • create historical branch and push to another remote
  • truncate recent history by creating a parentless base commit with plumbing
    • git commit-tree <commit>^{tree} (creates new commit from a tree)
  • rebase onto that base commit
    • git rebase --onto <newBase> <splitPointCommit>
• Recombine in a clone
  • fetch both remotes
  • git replace <recent_fourth_sha> <historical_fourth_sha>
• Effects/notes
  • git log shows full history
  • SHA displayed remains the original (the one being “replaced”), but content comes from replacement
  • git cat-file -p <old> shows replaced data (including different parent)
  • replacement stored as a ref
    • refs/replace/<oldsha>
  • can share by pushing that ref

Credential Storage

Problem being solved

• SSH can use keys (possibly no passphrase) → no repeated prompts
• HTTP always needs username/password
  • 2FA tokens make passwords harder to type/manage

Built-in credential helper approaches

• No caching (default)
  • prompts every connection
• cache
  • stores credentials in memory
  • not written to disk
  • purges after timeout (default 15 minutes / 900s)
• store
  • writes credentials to plain-text file (default ~/.git-credentials)
  • never expires
  • downside: cleartext password on disk
• macOS keychain helper (osxkeychain)
  • stores encrypted in system keychain; persists
• Git Credential Manager (Windows/macOS/Linux)
  • uses platform-native secure stores

Configuration

• Set helper
  • git config --global credential.helper <helper>
• Helper options
  • store file location
    • git config --global credential.helper 'store --file <path>'
  • cache timeout
    • git config --global credential.helper 'cache --timeout <seconds>'
• Multiple helpers
  • Git queries helpers in order until one returns credentials
  • When saving, Git sends creds to all helpers (each decides what to do)
• Example .gitconfig pattern shown
  • thumbdrive store + memory cache fallback

Under the hood (git credential)

• Git’s root credential command
  • git credential <action>
  • communicates via stdin/stdout key-value protocol
• Example action explained: fill
  • Git provides what it knows (e.g., protocol, host)
  • blank line ends input
  • credential system outputs what it found (username/password)
  • if unknown, Git prompts user and outputs what user entered
• How helpers are invoked (forms)
  • foo → runs git-credential-foo
  • foo -a --opt=bcd → runs git-credential-foo -a --opt=bcd
  • /absolute/path/foo -xyz → runs that program
  • !<shell> → executes shell code
• Helper action set (slightly different terms)
  • get request credentials
  • store save credentials
  • erase remove credentials
• Output rules
  • for get: helper may output additional key=value lines (overriding existing)
  • for store/erase: output ignored
• git-credential-store example shown
  • store: git credential-store --file <file> store
  • get: git credential-store --file <file> get
  • file format: credential-decorated URL per line
    • https://user:pass@host

Custom credential helper example: read-only shared store

• Use case described
  • team-shared credentials in shared directory
  • don’t want to copy to personal credential store
  • credentials change often
• Requirements (as listed)
  • only handle get; ignore store/erase
  • read git-credential-store-compatible file format
  • allow configurable path (--file)
• Implementation outline shown (Ruby)
  • parse options
  • exit unless action is get and file exists
  • read stdin key=value pairs until blank line
  • scan credential file; match on protocol/host/username
  • output protocol/host/username/password if found
• Configure with helper short name
  • git config --global credential.helper 'read-only --file <shared_path>'

Chapter Summary

• You now have advanced tools to:
  • select commits and ranges precisely
  • stage/commit partial changes interactively
  • temporarily shelve work (stash) and safely remove untracked artifacts (clean)
  • sign and verify tags/commits with GPG, and optionally enforce signed merges
  • search code and history efficiently (grep, log pickaxe/regex, line history)
  • rewrite local history confidently (amend, interactive rebase; filter-branch caveats)
  • understand reset and checkout via the three-tree model
  • handle complex merges (whitespace strategies, manual merges, combined diffs, undo merges, subtree merges, rerere)
  • debug regressions (blame, bisect, automated bisect runs)
  • manage nested dependencies with submodules (setup, update, push safety, conflicts, tips, caveats)
  • transfer Git data offline (bundles)
  • “graft” history with virtual object replacement (replace)
  • manage credentials with helpers (including writing your own)