Git merge or rebase: choose by how the branch is shared

Picture the history before choosing

Suppose main has moved forward while feature contains two of your commits. Merge combines both lines of development without replacing those commits; when histories have diverged, it normally adds a merge commit. If no divergence needs combining, Git may simply fast-forward the branch pointer.

Rebase takes your feature commits and applies their changes on the new base. Their identifiers change because their ancestry changes. The resulting line can be easier to read, but collaborators holding the old commits now have a different history. Choose according to how the branch is used and the repository’s rules.

Prepare the branch and update your information

Start with git status and finish or safely set aside uncommitted work. Fetch the remote before deciding how far behind you are. git fetch origin updates origin/main; it does not automatically update the local main branch. That distinction prevents integrating an out-of-date local reference by mistake.

The preparation below assumes the remote is origin and the branch is feature. Creating a backup branch gives you a reference to the current commits before integration. Choose a new backup name if one already exists. Then use the merge or rebase workflow for origin/main, rather than running both indiscriminately.

git status
git fetch origin
git switch feature
git branch backup-feature

Use merge to preserve the branch history

Merging is a straightforward option when existing commits must remain stable. Inspect the branch and review any conflict resolution before completing the merge.

git switch feature
git merge origin/main

Rebase local work deliberately

Rebase can make a local feature branch linear. Resolve conflicts carefully, inspect the resulting diff and rerun relevant checks. If the operation is wrong, use the matching abort command before proceeding.

git switch feature
git rebase origin/main

Resolve the meaning of a conflict, not just its markers

A conflict can mean that two edits express different business rules. Read both versions and the surrounding code. Removing the markers alone does not establish which behavior is correct. After editing, stage each resolved file with git add and inspect the staged diff.

For an unfinished merge, complete with git merge --continue or cancel with git merge --abort. For rebase, use git rebase --continue or git rebase --abort. Rebase can stop again on a later commit because it replays changes individually. Do not use --skip merely to silence a conflict: it can drop that commit’s changes.

Review and recover without discarding work blindly

After integration, compare the result with the expected changes and run the repository’s relevant checks. If a previously published branch was rebased, coordinate before updating the remote. --force-with-lease can guard against an unexpected remote value, but it is not a substitute for coordination or permission to rewrite history.

If integration went wrong after completion, inspect the backup branch and git reflog. Reflog records local reference movements and may help locate the earlier state. Create a recovery branch from the identified commit before considering a reset. Avoid reset --hard as a first response when uncommitted work may still be present.

git reflog --date=iso