Git Filter-Branch vs Manual Rebase: Restructuring Repository History

The Problem

Recently, while working on the RENDER project, I had a repository with this structure:

terminal-code/
├── packages/
│   └── astro-terminal-code/
│       ├── package.json
│       ├── README.md
│       └── src/

But I needed it to be:

terminal-code/
├── package.json
├── README.md
└── src/

The challenge? I wanted to preserve the entire commit history while restructuring the files across all commits, not just the latest one.

Approach 1: Manual Rebase Strategy

My usual approach for this type of problem involves manually going through each commit:

# 1. Start interactive rebase from root
git rebase -i --root

# 2. Mark each commit as 'edit'
# 3. For each commit, manually:
git reset --soft HEAD~1
# Move files manually
mv packages/astro-terminal-code/* .
rm -rf packages/
git add -A
git commit --amend --no-edit

# 4. Continue to next commit
git rebase --continue

# 5. Repeat until all commits are processed

Pros of Manual Rebase:

✅ Full control over each commit
✅ Can make different changes per commit if needed
✅ Easy to understand what’s happening
✅ Can abort/fix issues at any step

Cons of Manual Rebase:

❌ Time-consuming for many commits
❌ Prone to human error
❌ Interactive editor issues in some environments
❌ Repetitive and tedious process

Approach 2: Git Filter-Branch

Then I discovered git filter-branch - a powerful command that can rewrite entire repository history in one go:

# Single command to restructure entire history
FILTER_BRANCH_SQUELCH_WARNING=1 git filter-branch \
  --tree-filter 'if [ -d packages/astro-terminal-code ]; then 
    mv packages/astro-terminal-code/* . 2>/dev/null || true; 
    mv packages/astro-terminal-code/.* . 2>/dev/null || true; 
    rm -rf packages; 
  fi' HEAD

Pros of Filter-Branch:

✅ One command handles entire history
✅ Consistent changes across all commits
✅ Fast execution
✅ No interactive editor issues
✅ Atomic operation - all or nothing

Cons of Filter-Branch:

❌ Less granular control
❌ Can be dangerous if command is wrong
❌ Harder to debug if something goes wrong
❌ Rewrites all commit hashes

Real-World Comparison

Let me show you the actual results from my RENDER project restructuring:

Before:

$ git log --oneline
65e77b3 🔥 Update branding: SandikoOS → RENDER
a2219f5 🚀 FOUNDATION: SandikoOS Ecosystem - Phase 1

$ git show --name-only a2219f5
packages/astro-terminal-code/README.md
packages/astro-terminal-code/package.json
packages/astro-terminal-code/src/index.ts
packages/astro-terminal-code/src/processor.ts

After Filter-Branch:

$ git log --oneline
31a26da 🔥 Update branding: SandikoOS → RENDER
064115d 🚀 FOUNDATION: SandikoOS Ecosystem - Phase 1

$ git show --name-only 064115d
README.md
package.json
src/index.ts
src/processor.ts

Time taken:

Manual rebase: ~10-15 minutes (with interactive editor struggles)
Filter-branch: ~5 seconds

When to Use Each Approach

Use Manual Rebase When:

You need different changes per commit
You want to review each commit individually
You’re learning Git and want to understand the process
You have complex merge conflicts to resolve

Use Filter-Branch When:

You need consistent changes across all commits
You have many commits to process
You want a fast, automated solution
You’re confident in your filter command

Modern Alternative: Git Filter-Repo

For new projects, consider git filter-repo (requires separate installation):

# More modern and safer alternative
git filter-repo --path-rename packages/astro-terminal-code/:

Safety Tips

Regardless of which approach you choose:

Always backup your repository first
Test on a clone before applying to main repo
Use --force-with-lease when pushing rewritten history
Coordinate with team before rewriting shared history

# Safe backup and testing workflow
git clone original-repo test-repo
cd test-repo
# Apply your changes
git push --force-with-lease origin main

Conclusion

Both approaches have their place in a developer’s toolkit. For the RENDER project restructuring, git filter-branch was clearly the winner - it saved me significant time and eliminated the interactive editor issues I was facing.

However, the manual rebase approach taught me a lot about Git internals and gives me confidence to handle complex history rewriting scenarios.

My recommendation: Start with understanding the manual approach, then graduate to git filter-branch for efficiency. Your future self will thank you for learning both! 🚀

This article is part of my journey building the RENDER ecosystem - revolutionizing desktop development with web technologies. Follow along for more Git tips and development insights!