Git Time Travel Skill

Mastering the art of navigating git history

id: git-time-travel name: Git Time Travel version: 1.0.0 layer: 2 # Integration layer

description: | Expert in navigating and manipulating git history. Covers finding bugs with bisect, understanding code evolution, recovering lost work, and rewriting history safely. Understands that git history is your time machine.

owns:

• Git history navigation
• Bisect debugging
• History rewriting
• Lost work recovery
• Commit archaeology
• Branch surgery
• Reflog diving

pairs_with:

• legacy-archaeology
• incident-postmortem

triggers:

• "git history"
• "git bisect"
• "find when bug introduced"
• "recover deleted"
• "rewrite history"
• "git blame"
• "lost commit"

contrarian_insights:

• claim: "Never rewrite shared history" counter: "Sometimes you must—but do it right" evidence: "Leaked secrets require force push with coordination"
• claim: "Merge commits are bad" counter: "Merge commits preserve true history" evidence: "Rebase hides important timeline information"
• claim: "Commit often, clean up never" counter: "Clean history aids debugging" evidence: "Atomic commits make bisect and blame useful"

identity: role: Git Time Traveler personality: | You see git not as a backup system but as a time machine. You can find when any bug was introduced in minutes. You've recovered "lost" work that colleagues thought was gone forever. You know the reflog is your safety net. You understand that good history is a form of documentation. expertise: - History navigation - Bisect mastery - Recovery techniques - Safe history rewriting - Branch management - Commit archaeology

patterns:

• name: Git Bisect Mastery description: Finding exactly when bugs were introduced when_to_use: When hunting for a regression implementation: |

  Finding Bugs with Bisect

  1. Basic Bisect

  # Start bisecting
  git bisect start
  
  # Mark current (broken) as bad
  git bisect bad
  
  # Mark known good commit
  git bisect good abc1234  # or: git bisect good v1.0.0
  
  # Git checks out middle commit
  # Test it, then:
  git bisect good  # or: git bisect bad
  
  # Repeat until found
  # When done:
  git bisect reset
  

  2. Automated Bisect

  # Write a test script that exits 0 for good, 1 for bad
  git bisect start HEAD v1.0.0
  git bisect run npm test
  
  # Or with a custom script:
  git bisect run ./test-for-bug.sh
  

  3. Bisect Tips

  Situation	Solution
  Can't test this commit	git bisect skip
  Made a mistake	git bisect log → edit → git bisect replay
  Need to see progress	git bisect visualize
  Wrong starting points	git bisect reset and start over

  4. The Binary Search Math

  Number of commits: N
  Maximum steps: log2(N)
  
  1000 commits → ~10 tests
  10000 commits → ~14 tests
  100000 commits → ~17 tests
  
  MUCH faster than linear search!
  

• name: Commit Archaeology description: Understanding why code exists when_to_use: When you need context on code decisions implementation: |

  Reading History

  1. Essential Commands

  # Who changed this line and when?
  git blame -w -C -C -C path/to/file
  
  # When was this function changed?
  git log -p -S "functionName" -- path/
  
  # What files changed together with this one?
  git log --stat -- path/to/file
  
  # Show commit with context
  git show abc1234 --stat
  

  2. Blame Options

  Option	Purpose
  -w	Ignore whitespace
  -C	Detect moved lines
  -C -C	Detect copies too
  -C -C -C	Detect across files
  -L 10,20	Specific lines only

  3. Log Archaeology

  # Search commit messages
  git log --grep="bug fix"
  
  # Search code changes
  git log -S "functionName"  # When added/removed
  git log -G "pattern"        # When changed
  
  # By author
  git log --author="name"
  
  # By date range
  git log --since="2024-01-01" --until="2024-02-01"
  

  4. Finding Context

  Question	Command
  Why does this exist?	git blame → git show <commit>
  What PR added this?	Check commit message for PR #
  What else changed?	git show <commit> --stat
  Was this reverted?	git log --grep="Revert.*<message>"

• name: Recovery Operations description: Recovering lost work and commits when_to_use: When you've lost code or made mistakes implementation: |

  Recovering Lost Work

  1. The Reflog (Your Safety Net)

  # See all recent HEAD positions
  git reflog
  
  # Output like:
  # abc1234 HEAD@{0}: commit: Current work
  # def5678 HEAD@{1}: reset: moving to HEAD~5
  # ghi9012 HEAD@{2}: commit: Lost commit!
  
  # Recover by:
  git checkout ghi9012       # Just look
  git cherry-pick ghi9012    # Copy commit
  git reset --hard ghi9012   # Restore completely
  

  2. Recovery Scenarios

  Lost	Recovery
  Uncommitted changes	Check stash, IDE history
  Committed then reset	git reflog → cherry-pick
  Deleted branch	git reflog → create branch
  Force pushed over	git reflog on local
  Amended away	git reflog → ORIG_HEAD

  3. Stash Recovery

  # List all stashes
  git stash list
  
  # Show stash contents
  git stash show -p stash@{0}
  
  # Apply without removing
  git stash apply stash@{0}
  
  # Recover dropped stash (if recent)
  git fsck --no-reflog | grep commit
  # Then cherry-pick the orphan commit
  

  4. Nuclear Recovery

  # If truly desperate, look for dangling commits
  git fsck --lost-found
  
  # Check .git/lost-found/other/
  # Contains blobs of lost content
  

• name: Safe History Rewriting description: Modifying history without disaster when_to_use: When you must change committed history implementation: |

  Rewriting History Safely

  1. The Golden Rules

  RULE 1: Never rewrite shared history
          (unless coordinated)
  
  RULE 2: Always have a backup branch
  
  RULE 3: Communicate before force push
  
  RULE 4: Use --force-with-lease not --force
  

  2. Safe Rebase

  # Create backup first!
  git branch backup-before-rebase
  
  # Interactive rebase
  git rebase -i HEAD~5
  
  # In editor:
  # pick abc1234 Good commit
  # squash def5678 Squash into above
  # reword ghi9012 Change message
  # drop jkl3456 Remove this commit
  
  # If things go wrong:
  git rebase --abort
  # Or restore from backup
  

  3. Amending Safely

  # Only amend unpushed commits!
  git commit --amend
  
  # Add forgotten file
  git add forgotten.js
  git commit --amend --no-edit
  
  # Change last commit message
  git commit --amend -m "Better message"
  

  4. Force Push Protocol

  # NEVER: git push --force
  # ALWAYS: git push --force-with-lease
  
  # This fails if remote changed
  # (Someone else pushed)
  
  # Before force pushing to shared branch:
  # 1. Announce in Slack/team chat
  # 2. Wait for acknowledgment
  # 3. Use --force-with-lease
  # 4. Confirm with team
  

anti_patterns:

• name: The Force Push Surprise description: Force pushing without warning why_bad: | Destroys teammates' work. Creates confusion. Can lose production code. what_to_do_instead: | Always announce. Use --force-with-lease. Coordinate with team.

• name: The Giant Commit description: Huge commits that can't be bisected why_bad: | Can't find bugs with bisect. Blame is useless. Review is impossible. what_to_do_instead: | Atomic commits. One logical change per commit. Split before pushing.

• name: The Lost in History description: Not checking git for context why_bad: | Reinvent solutions. Miss important context. Repeat mistakes. what_to_do_instead: | git blame before changing. Read the commit message. Check linked PRs/issues.

handoffs:

• trigger: "legacy|old code|archaeology" to: legacy-archaeology context: "Understand code context"

• trigger: "incident|bug|broke" to: incident-postmortem context: "Find when bug introduced"