What merging a branch means and when you need it

Merging combines the work from two separate branches into one. When you finish work on a feature branch — say, a new login page — you merge it back into your main branch so that code becomes part of the project everyone uses. Git records which commits came from which branch and combines the files automatically, as long as you didn't both change the same lines.

You merge branches when a feature is done and tested, when you want to bring in bug fixes from another branch, or when you're ready to integrate someone else's work into the shared codebase. The merge creates a record of when and how the branches came together.

Key Takeaways

  • Switch to the branch you want to merge into (usually main or master) before running the merge command.
  • The command git merge branch-name combines the other branch's commits into your current branch.
  • A merge conflict happens when both branches changed the same lines; Git will mark the conflicting sections and ask you to choose which version to keep.
  • After resolving conflicts, you stage the files with git add and complete the merge with git commit.
  • Use git log --oneline --graph to see the branch history and confirm the merge worked.

The basic merge: no conflicts

Start by switching to the branch you want to merge into. Usually this is main or master. Type git checkout main and press Enter. If you're using Git 2.23 or newer, you can also type git switch main.

Next, pull the latest changes from the remote repository so you're working with current code. Type git pull origin main and press Enter. This prevents you from merging stale code.

Now run the merge command. Type git merge feature-branch-name (replace feature-branch-name with the actual name of the branch you're merging in) and press Enter. Git will combine the commits from that branch into main. If no files conflict, the merge completes automatically and you'll see a message like "Merge made by the 'recursive' strategy."

Push the merged result back to the remote repository so your team sees the change. Type git push origin main and press Enter.

When Git stops and asks you to fix conflicts

A merge conflict happens when both branches changed the same lines in the same file. Git cannot automatically decide which version to keep, so it pauses the merge and marks the problem areas in your files.

When you run git merge and a conflict occurs, Git will print a message like "CONFLICT (content): Merge conflict in filename.txt" and list the files involved. Open one of the conflicted files in your text editor. You'll see sections marked like this:

<<<<<<< HEAD your current branch's version of the code ======= the other branch's version of the code >>>>>>> feature-branch-name

The section between <<<<<<< HEAD and ======= is what's in your current branch. The section between ======= and >>>>>>> is what's in the branch you're merging in. Delete the markers and the version you don't want, keeping only the code that should be there. If both versions are needed, keep both and remove only the markers.

Repeat this for every conflicted file. When you've fixed them all, type git add . to stage the resolved files, then type git commit -m "Merge feature-branch-name into main" to complete the merge. Push the result with git push origin main.

Checking your merge before you push

Before pushing a merge to the remote repository, you can check what changed. Type git log --oneline -5 to see the last five commits. You should see your merge commit listed at the top with a message like "Merge branch 'feature-branch-name' into 'main'".

To see which files were actually changed by the merge, type git diff HEAD~1 HEAD. This shows the difference between the commit before the merge and the merge commit itself. Review the changes to make sure nothing unexpected happened.

If something looks wrong and you haven't pushed yet, you can undo the merge. Type git reset --hard HEAD~1 to go back to the state before the merge. Then investigate the problem and try again.

Deleting the branch after a successful merge

Once a branch is merged and pushed, you usually don't need the feature branch anymore. Delete it locally with git branch -d feature-branch-name. Git will refuse to delete if there are commits on that branch that aren't merged anywhere, which is a safety feature.

To also delete the branch from the remote repository, type git push origin --delete feature-branch-name. This cleans up the repository so old branches don't clutter the list when you run git branch -a.

If you accidentally delete a branch, you can recover it. Type git reflog to see a history of where HEAD has pointed, find the commit you want, and type git checkout -b recovered-branch-name commit-hash to recreate the branch at that point.

Understanding fast-forward merges

Sometimes Git performs a fast-forward merge instead of a regular merge. This happens when the branch you're merging in is directly ahead of your current branch — meaning no new commits were made to main after the feature branch was created.

In a fast-forward merge, Git simply moves the main branch pointer forward to the same commit as the feature branch. No merge commit is created. You'll see a message like "Fast-forward" instead of "Merge made by the 'recursive' strategy."

Fast-forward merges are simpler and keep the history cleaner, but they don't create a record showing when the branches came together. If you want a merge commit even for fast-forward situations, use git merge --no-ff feature-branch-name. The --no-ff flag forces Git to create a merge commit regardless.

Frequently Asked Questions

What's the difference between merge and rebase?

Merge combines two branches and creates a merge commit showing they came together. Rebase replays one branch's commits on top of another, creating a linear history with no merge commit. Merge is safer for shared branches; rebase is cleaner but rewrites history and should not be used on branches other people are working on.

Can I merge a branch into itself by accident?

No. If you're on main and run git merge main, Git recognizes that you're trying to merge a branch into itself and does nothing. It will print "Already up to date." and exit without making any changes.

What if the merge creates conflicts in a file I didn't edit?

This usually means someone else edited that file on the other branch while you edited it on yours. Open the file, find the conflict markers, and decide which version is correct. If you're unsure, talk to the person who made the other change before resolving it.

How do I see what commits are in a branch before I merge it?

Type git log main..feature-branch-name to see all commits in feature-branch-name that are not in main. This shows you exactly what will be added by the merge before you run it.

Can I undo a merge after I've pushed it?

Yes, but it's more complicated. Type git revert -m 1 commit-hash where commit-hash is the merge commit you want to undo. This creates a new commit that reverses the merge. Then push the revert commit. Do not use git reset on a commit that's already been pushed, because it rewrites history and confuses other people's repositories.