The Spaghetti History Problem
You’ve finished your feature branch, and now it’s time to integrate it back into `main`. The obvious command is `git merge`. It works, but on a busy project, your Git history can quickly start to look like a plate of spaghetti when viewed with `git log --graph`. There are merge commits everywhere, and tracing the history of a feature becomes a tangled mess. There is another way: `git rebase`. It’s a powerful tool for keeping your history clean and linear, but it comes with its own set of rules.
What is Git Merge?
Merging takes all the commits from your feature branch and combines them with the `main` branch. Critically, it creates a special new commit, a "merge commit," that ties the two histories together.
Pros: It’s non-destructive. It preserves the exact, chronological history of what happened. It’s simple and easy to understand.
Cons: It clutters your project history with merge commits, making it hard to read.
# Switch to the receiving branch
git checkout main
# Merge the feature branch into it
git merge feat/my-new-feature
What is Git Rebase?
Rebasing does something magical. Instead of creating a merge commit, it takes all the commits from your feature branch, temporarily sets them aside, winds back the `main` branch to where you first branched off, pulls in the latest changes, and then replays your feature branch commits one by one on top of the newly updated `main`. The result is a perfectly linear history.
Pros: It creates a clean, easy-to-read commit history. It eliminates unnecessary merge commits.
Cons: It rewrites history (changing commit hashes), which can be dangerous on shared branches. It can be more complex to resolve conflicts.
# Switch to the branch you want to rebase
git checkout feat/my-new-feature
# Rebase it ONTO the main branch
git rebase main
# Now, main can be fast-forwarded
git checkout main
git merge feat/my-new-feature # This will be a "fast-forward" merge, no merge commit
The Golden Rule of Rebasing
This is the most important rule: NEVER rebase a public, shared branch that other developers are working on. Since rebase rewrites commit history, if you rebase a branch that your teammate has also pulled, you’ve just created divergent histories. When they try to pull again, Git will see two different histories and create a confusing mess. Only rebase branches that you are working on alone.
Which One Should You Use?
A popular and safe workflow is to use rebase for your private feature branches and merge for integrating into the main public branch.
Here’s the workflow:
- You are working on `feat/my-feature`.
- While you are working, `main` gets updated with new commits.
- To keep your feature branch up-to-date, you run `git pull --rebase origin main`. This rebases your local commits on top of the latest `main` code, keeping your history clean.
- When your feature is complete, you open a pull request.
- The feature is then merged into `main` using a standard merge (often with a "squash and merge" option on GitHub to combine all your feature commits into one clean commit).
This hybrid approach gives you the best of both worlds: a clean, linear history for your feature development, and a safe, traceable merge into your main codebase.