Documentation
Advanced Git: Mastering Complex Operations
Rewriting History

Rewriting History

Critical Warning: History rewriting operations fundamentally alter commit SHA-1 hashes, creating divergent repository states that can cause severe synchronization issues for collaborators. These operations should only be performed on private branches or with explicit team coordination and acknowledgment of the implications.

Architectural Rationale: Why History Rewriting Exists

Git’s history rewriting capabilities stem from its fundamental design as a content-addressable object store. Unlike traditional version control systems that treat history as immutable, Git recognizes that commit history serves as both a technical record and a communication tool. The ability to refine this history before sharing enables teams to maintain clarity and maintainability.

The Dual Nature of Git History

Before Publication (Private Branches):

  • History is a working draft
  • Commits serve as save points during development
  • Messy, experimental, or incomplete work is acceptable
  • Rewriting improves clarity without consequences

After Publication (Shared Branches):

  • History becomes a permanent record
  • Other developers may have based work on these commits
  • Rewriting creates parallel universes requiring manual reconciliation
  • Changes must be coordinated across the team

Technical Implication: The SHA-1 hash includes parent commit references. Modifying any commit creates a new hash, which cascades to all descendant commits—fundamentally changing the commit graph structure.

Strategic Use Cases for History Rewriting

Understanding when history rewriting provides value versus when it introduces unnecessary risk is critical for effective Git usage.

Use Case 1: Commit Organization and Clarity

Problem Context: During feature development, commits accumulate organically—experimental attempts, debug logging additions, typo fixes, and incremental progress. This raw history obscures the logical progression of the feature.

Example Raw History:

abc123 Add user authentication
def456 Fix typo in auth function
ghi789 Debug: Add console.log statements
jkl012 Remove debug statements
mno345 Actually fix auth bug
pqr678 Fix typo in commit message

After Rewriting:

stu901 Implement user authentication system
  - JWT token generation
  - Password hashing with bcrypt
  - Session management

Strategic Benefit: Code reviewers see logical progression rather than implementation artifacts. Future developers using git blame or git log understand the feature’s intent without navigating noise.

Use Case 2: Sensitive Data Removal

Critical Scenario: Accidental credential commits represent a severe security vulnerability. Even after removing credentials in a subsequent commit, they persist in repository history and remain accessible.

Problem Manifestation:

# Commit 1: Add config file with API keys
git add config.json  # Contains: API_KEY="secret-key-12345"
git commit -m "Add configuration"

# Commit 2: Remove keys
git add config.json  # Now contains: API_KEY="<redacted>"
git commit -m "Remove sensitive data"

Security Gap: git log -p or git show <commit-1> still exposes the original credentials. Any clone of the repository contains the sensitive data.

Required Solution: Complete history rewrite to eliminate all traces:

git filter-repo --path config.json --invert-paths
# Removes file from entire history
# Alternative: Use BFG Repo-Cleaner for large repositories

Post-Remediation Protocol:

  1. Immediately rotate compromised credentials
  2. Force-push cleaned history
  3. Require all team members to re-clone repository
  4. Audit access logs for potential credential usage

Use Case 3: Maintaining Clean Project History

Philosophical Approach: Repository history serves as project documentation. A well-organized history enables:

  • Efficient Debugging: git bisect performs faster with logical commits
  • Code Archaeology: Understanding why decisions were made
  • Selective Reversion: Cleanly undo specific features without collateral damage
  • Onboarding: New team members understand project evolution

Anti-Pattern History:

- WIP
- more changes
- fix
- fix fix
- final fix
- actually final this time
- merge conflicts resolved

Well-Structured History:

- Implement payment processing integration
- Add customer invoice generation
- Create email notification system
- Integrate with third-party shipping API

Technical Mechanism: Interactive rebase enables post-hoc organization of commits into coherent logical units before they enter the main branch.

Use Case 4: Correcting Branch Mistakes

Common Scenario: Beginning implementation on the wrong branch—starting feature work on main instead of a feature branch, or developing a hotfix on a feature branch.

Problem Impact:

  • Wrong branch tip moves forward
  • Creates merge complexity
  • Pollutes branch history with unrelated commits

Resolution Strategy:

# Scenario: 3 commits made on main that should be on feature-auth
git branch feature-auth  # Create branch at current position
git reset --hard HEAD~3  # Move main back 3 commits
git checkout feature-auth  # Switch to correct branch
# Commits now exist only on feature-auth

Why This Works: Branch creation is a pointer operation—feature-auth now references the commits, while main pointer moves backward. The commits themselves remain in the object database.

Core History Rewriting Operations

Operation 1: Amend Last Commit (git commit --amend)

Use Case: Modify the most recent commit before pushing.

Common Scenarios:

  • Typo in commit message
  • Forgot to stage a file
  • Need to add related changes to previous commit

Technical Behavior:

# Initial commit
git commit -m "Add user authentication"  # SHA: abc123

# Realize you forgot to stage tests
git add tests/auth_test.py

# Amend previous commit
git commit --amend --no-edit  # SHA: def456 (NEW hash)

Object-Level Changes:

  1. Creates new commit object with:
    • Same parent as abc123
    • Modified tree (includes auth_test.py)
    • Different SHA due to tree modification
  2. Updates branch reference to point to def456
  3. Original commit abc123 becomes unreferenced (garbage collected after ~90 days)

Critical Warning: If abc123 was already pushed, def456 represents a divergent history. Force-push required:

git push --force-with-lease origin feature-branch

--force-with-lease Safety: Verifies no one else pushed changes since your last fetch. Safer than --force which blindly overwrites.

Operation 2: Interactive Rebase (git rebase -i)

Capability Overview: Interactive rebase provides a text-editor interface for sophisticated commit graph manipulation.

Available Operations:

pick abc123 Add feature     # Keep commit as-is
reword def456 Fix bug       # Modify commit message
edit ghi789 Update tests    # Pause for amendments
squash jkl012 Fix typo      # Merge into previous commit
fixup mno345 Cleanup        # Squash without editing message
drop pqr678 Debug code      # Remove commit entirely

Practical Workflow Example:

Initial State (5 commits on feature branch):

git log --oneline
abc123 Add user model
def456 Add authentication
ghi789 Fix typo in auth
jkl012 Add tests
mno345 Fix test typo

Rebase Command:

git rebase -i HEAD~5

Editor Opens:

pick abc123 Add user model
pick def456 Add authentication
fixup ghi789 Fix typo in auth      # Squash into def456
pick jkl012 Add tests
fixup mno345 Fix test typo         # Squash into jkl012

Resulting History (3 clean commits):

pqr678 Add user model
stu901 Add authentication
vwx234 Add tests

Technical Process:

  1. Git checks out HEAD~5 (base commit)
  2. Replays each commit according to instructions
  3. Creates new commit objects with new SHAs
  4. Updates branch reference to final commit
  5. Original commits become unreferenced

Conflict Resolution:

# If conflicts occur during replay
git status  # Identify conflicted files
# Fix conflicts manually
git add <resolved-files>
git rebase --continue

# Or abort entire operation
git rebase --abort

Operation 3: Reset Operations (git reset)

Three Reset Modes: Understanding the differences prevents data loss.

Mode 1: --soft (Staging Area Preservation)

git reset --soft HEAD~1

Effect:

  • Moves branch pointer backward 1 commit
  • Keeps all changes staged
  • Working directory unchanged

Use Case: Redo commit message or restructure staged changes

git reset --soft HEAD~1
# Edit files
git add additional-file.py
git commit -m "Better organized commit message"

Mode 2: --mixed (Default, Staging Cleared)

git reset HEAD~1
# Equivalent to: git reset --mixed HEAD~1

Effect:

  • Moves branch pointer backward
  • Unstages all changes
  • Working directory unchanged (files keep modifications)

Use Case: Restructure which changes go into which commits

git reset HEAD~2
# Now have 2 commits worth of changes unstaged
git add file1.py
git commit -m "First logical change"
git add file2.py
git commit -m "Second logical change"

Mode 3: --hard (Complete State Rollback)

git reset --hard HEAD~1

Effect:

  • Moves branch pointer backward
  • Clears staging area
  • DISCARDS all working tree changes

Use Case: Completely abandon recent work

Critical Warning: --hard destroys uncommitted changes. Always verify with:

git stash  # Safer alternative
git reset --hard HEAD~1
# If you regret it:
git stash pop  # Recover changes

Recovery from Accidental Hard Reset:

git reflog  # Find lost commit
# abc123 HEAD@{1}: commit: Lost work
git reset --hard abc123  # Restore to that state

Operation 4: Filter Operations (Complete History Rewrite)

Use Case: Remove files/data from entire repository history.

Modern Tool: git filter-repo (replaces deprecated git filter-branch)

Installation:

pip install git-filter-repo

Common Scenarios:

Scenario 1: Remove Accidentally Committed Large Binary

# Remove file from all history
git filter-repo --path large-file.bin --invert-paths

# Result: File never existed in any commit

Scenario 2: Remove Sensitive Configuration

# Remove all traces of secrets.yaml
git filter-repo --path config/secrets.yaml --invert-paths

# More aggressive: Remove any file containing "password"
git filter-repo --path-glob '*password*' --invert-paths

Scenario 3: Extract Subdirectory as New Repository

# Keep only backend/ directory in history
git filter-repo --path backend/ --path-rename backend/:
# Creates repository where backend/ becomes root

Post-Filter Protocol:

# Force-push rewritten history
git push origin --force --all
git push origin --force --tags

# Team notification required:
# "Repository history rewritten. Delete your local clone and re-clone:
#  rm -rf old-repo
#  git clone <url>"

Why Re-clone Required: Local clones contain the old history. Pulling won’t work—Git sees completely different commit graphs.

Best Practices and Safety Protocols

Practice 1: Never Rewrite Public History (Without Coordination)

Public History Definition:

  • Any branch pushed to shared remote
  • Commits that other developers have based work on
  • Main/master/develop branches (typically protected)

Why This Matters:

# Developer A's state
main: A - B - C - D

# Developer A rewrites history
git rebase -i HEAD~2  # Squashes C and D
main: A - B - E

# Developer A force-pushes
git push --force origin main

# Developer B (still has old history)
main: A - B - C - D
# Developer B's commits C and D now diverge from remote
# Next pull creates merge conflicts resolving identical code

Exception: Coordinated team rewrite

  1. Announce history rewrite in advance
  2. Ensure no one has pending work on affected branches
  3. Provide clear instructions for re-synchronization
  4. Use --force-with-lease to detect unexpected pushes

Practice 2: Create Backup Branches

Always Create Safety Net:

# Before any history rewriting
git branch backup-before-rebase

# Perform risky operation
git rebase -i HEAD~10

# If disaster strikes
git reset --hard backup-before-rebase

Backup Branch Cleanup:

# After confirming rewrite success
git branch -D backup-before-rebase

Practice 3: Use --force-with-lease Over --force

Problem with --force:

git push --force origin feature-branch
# Overwrites remote regardless of what's there
# Can destroy other developers' pushed commits

Safety with --force-with-lease:

git push --force-with-lease origin feature-branch
# Only succeeds if remote matches your last fetch
# Fails if someone else pushed changes

How It Works:

  • Tracks remote branch state at last fetch
  • Compares remote state before push
  • Rejects push if remote changed unexpectedly
  • Forces explicit git fetch to see others’ changes

Example Protection:

# You: Last fetched when remote was at commit C
git rebase -i HEAD~3
git push --force-with-lease origin feature

# Meanwhile, teammate pushed commit D

# Result: Push rejected
! [rejected]        feature -> feature (stale info)
# Forces you to fetch and review commit D before overwriting

Practice 4: Understand Reflog as Safety Net

Reflog Mechanics: Git maintains a log of every position HEAD has referenced (past 90 days by default).

Recovery Scenarios:

Scenario 1: Accidental Hard Reset

git reset --hard HEAD~5  # Oops, too far
git reflog
# abc123 HEAD@{1}: reset: moving to HEAD~5
# def456 HEAD@{0}: commit: Important work

git reset --hard def456  # Recover lost commits

Scenario 2: Lost After Rebase Abort

git rebase -i HEAD~3
# Mess up during rebase
git rebase --abort

# Later: "Wait, I wanted those changes"
git reflog
git cherry-pick <commit-from-reflog>

Reflog Expiration Configuration:

# Extend reflog retention for critical repositories
git config gc.reflogExpire "365 days"
git config gc.reflogExpireUnreachable "180 days"

Practice 5: Test History Rewrites on Branches

Safe Experimentation Protocol:

# Create experimental branch
git checkout -b experiment-rebase

# Perform history rewriting
git rebase -i HEAD~10

# Verify result
git log --oneline
git diff main..experiment-rebase  # Should show no changes

# If satisfied, apply to real branch
git checkout main
git reset --hard experiment-rebase

# Cleanup
git branch -D experiment-rebase

Advanced Patterns and Edge Cases

Pattern 1: Selective Commit Extraction

Scenario: Extract specific commits from a messy branch to create clean feature branch.

# Current branch has 10 commits, but only 3 are relevant
git checkout -b feature-clean main

# Cherry-pick specific commits
git cherry-pick abc123  # Commit 3
git cherry-pick def456  # Commit 7
git cherry-pick ghi789  # Commit 9

# Result: Clean 3-commit feature branch

Pattern 2: Splitting Large Commits

Scenario: One commit contains multiple logical changes that should be separate.

# Start interactive rebase
git rebase -i HEAD~1

# Change "pick" to "edit" for the large commit
# Rebase pauses at that commit

# Reset to previous commit, keeping changes unstaged
git reset HEAD^

# Stage and commit changes in logical chunks
git add file1.py
git commit -m "First logical change"

git add file2.py file3.py
git commit -m "Second logical change"

# Continue rebase
git rebase --continue

Pattern 3: Reordering Commits

Scenario: Commits are in suboptimal order for logical narrative.

git rebase -i HEAD~5

# In editor, reorder lines (top-to-bottom = oldest-to-newest)
pick ghi789 Add feature C
pick abc123 Add feature A
pick def456 Add feature B

Conflict Warning: Reordering commits with overlapping file changes will cause conflicts. Git replays commits in new order—if commit B depends on commit A, swapping them creates merge conflicts.

Pattern 4: Recovering from Rebase Disasters

Nuclear Option: Abort and Restart

# During rebase when things go wrong
git rebase --abort

Surgical Recovery: Fix Mid-Rebase

# Conflict during rebase
git status  # See conflicted files

# Option 1: Fix and continue
# Edit files to resolve conflicts
git add <resolved-files>
git rebase --continue

# Option 2: Skip this commit
git rebase --skip

# Option 3: Use their version for specific files
git checkout --theirs <file>
git add <file>
git rebase --continue

Common Pitfalls and Solutions

Pitfall 1: Force-Pushing to Protected Branch

Problem: Accidentally force-pushing to main/master can destroy production history.

Prevention:

# Configure branch protection
git config branch.main.pushRemote no_push
# Or use Git hosting platform protection (GitHub/GitLab branch rules)

Recovery:

# If you force-pushed to main
git reflog origin/main  # May show old state
git push origin <old-commit>:main --force-with-lease

Pitfall 2: Rebasing Already-Pushed Commits

Symptom: After force-push, teammates get merge conflicts on pull.

Team Recovery Protocol:

# Each team member:
git fetch origin
git reset --hard origin/feature-branch
# Discards local commits on rewritten branch
# Or cherry-pick local work onto new history:
git cherry-pick <their-local-commits>

Pitfall 3: Losing Commits During Interactive Rebase

Problem: Deleting line in interactive rebase editor drops commit permanently.

Prevention: Always use drop command explicitly rather than deleting lines:

# Explicit (recoverable via reflog)
drop abc123 Unwanted commit

# Implicit (harder to recover)
# (line deleted from editor)

Recovery:

git reflog
git cherry-pick abc123  # Restore dropped commit

Pitfall 4: Amending Merge Commits

Problem: git commit --amend on a merge commit can create invalid history.

Safe Alternative:

# Don't amend merge commits
# Instead, create fixup commit
git commit -m "Fix issue in merge commit"

Decision Framework: To Rewrite or Not to Rewrite

Rewrite History When:

✅ On private feature branches before creating PR ✅ Sensitive data accidentally committed (immediate action required) ✅ Organizing commits for code review (improves reviewer experience) ✅ Correcting branch mistakes before publishing ✅ Splitting/combining commits for logical clarity

Don’t Rewrite History When:

❌ Commits are already on main/master/develop ❌ Other developers have branched from your commits ❌ Purely cosmetic fixes on old commits (not worth the risk) ❌ Learning Git (master basic operations first) ❌ Unclear about consequences (when in doubt, don’t rewrite)

Quick Reference: History Rewriting Commands 

# Amend last commit
git commit --amend
git commit --amend --no-edit

# Interactive rebase (last 3 commits)
git rebase -i HEAD~3
git rebase -i <base-commit>

# Reset modes
git reset --soft HEAD~1   # Keep changes staged
git reset HEAD~1          # Keep changes unstaged (default --mixed)
git reset --hard HEAD~1   # Discard all changes

# Filter operations (modern)
git filter-repo --path <file> --invert-paths

# Force push safely
git push --force-with-lease origin <branch>

# Recovery
git reflog
git reset --hard <commit-from-reflog>

# Backup before rewriting
git branch backup-branch

Advanced Recovery Techniques

Technique 1: Finding Lost Commits 

# List all commits not reachable from any branch
git fsck --lost-found

# Search reflog for specific commit
git reflog | grep "commit message fragment"

# Recover specific commit
git cherry-pick <lost-commit-sha>

Technique 2: Recovering After Force-Push

If you have local backup:

git push origin backup-branch:main --force-with-lease

If teammate has correct history:

# Teammate creates backup
git push origin main:main-backup

# You restore from backup
git fetch origin main-backup:main
git push origin main --force-with-lease

Integration with Team Workflows

Workflow 1: Feature Branch Cleanup

Standard Practice:

# 1. Develop feature with messy commits
git checkout -b feature-payment
# ... many commits ...

# 2. Before PR: Clean up history
git rebase -i main

# 3. Force-push cleaned branch
git push --force-with-lease origin feature-payment

# 4. Create pull request with clean history

Workflow 2: Main Branch Protection

GitHub/GitLab Configuration:

  • Require pull requests
  • Disable force-push to main
  • Require linear history (rebase or squash merge)

Result: History rewriting allowed on feature branches, impossible on main.

Summary: Principles of Safe History Rewriting

  1. Never rewrite published history without team coordination
  2. Always create backup branches before risky operations
  3. Use --force-with-lease instead of --force
  4. Understand reflog as your safety net
  5. Test rewrites on experimental branches first
  6. Communicate clearly when force-pushing shared branches
  7. Rotate credentials immediately when removing sensitive data
  8. Prefer small, focused rewrites over large-scale history changes

Philosophical Approach: History rewriting is a powerful tool for creating clear, maintainable repositories. Used responsibly on private branches, it improves code review quality and project maintainability. Used carelessly on shared branches, it creates chaos. The key is understanding the boundary between your workspace and shared history.

Master Git’s history manipulation safely Back to Advanced Workflows

Interactive Rebase