Rebase versus Merge: Workflows and Guidelines

Both git merge and git rebase serve to integrate changes from one branch into another, but they create very different commit history topologies.

1. Merging (Integrate via Joint History)

Merging takes the content of the feature branch and integrates it into the target branch, creating a new merge commit:

git switch main
git merge feature-auth

• Pros: Safe operation. Preserves the historical timeline of when branches were created and merged.
• Cons: Can result in a cluttered history graph with many merge commits if many developers are working in parallel.

2. Rebase (Integrate via Moving Bases)

Rebasing moves your feature branch commits to the tip of the target branch, rewriting history to make it look like you started your work from the latest commit:

git switch feature-auth
git rebase main

• Pros: Creates a clean, linear commit history graph with no merge commits.
• Cons: Rewrites commit hashes. If conflicts occur, you must resolve them for each commit in the feature branch.

3. The Golden Rule of Rebasing

[!IMPORTANT] Never rebase branches that have been pushed to public shared repositories.

Rebasing rewrites commits. If other developers have already pulled your branch and are working on top of it, rebasing will force them to manually reconcile their histories, leading to confusion and lost work. Only rebase local, unpushed branches to clean up your commit history before sharing.