How to Merge Two Branches in Git: A Step-by-Step Guide

Merging two branches in Git combines the changes from one branch into another, creating a shared history while keeping both branch names available. You’ll choose the branch that should receive the changes, merge the source branch into it, and check the result. Before you start, commit or stash any unfinished work so it is not confused with the merge.

What You’ll Need

• A Git repository with the two branches you want to merge.
• A terminal or command prompt opened in that repository, or a Git client that provides equivalent branch and merge actions.
• Permission to update the destination branch, especially if you plan to push it to a shared remote.

Step-by-Step

1. Check your current work. Run git status. If you have changes you want to keep, either commit them or temporarily stash them with git stash. A merge may be blocked when uncommitted changes could be overwritten. Do not discard work unless you are certain you no longer need it.
2. Fetch the latest remote information. If the branches are shared on a remote such as origin, run git fetch origin. Fetching updates your local records of remote branches without merging their changes into your current branch. If you work entirely locally, you can skip this step.
3. Identify the source and destination. The destination is the branch that will receive changes; the source is the branch whose changes you want to bring in. For example, to merge feature into main, main is the destination and feature is the source. Check branch names with git branch; include -a to see remote-tracking branches too.
4. Switch to the destination branch. Run git switch main, replacing main with your destination branch. Older Git versions also support git checkout main. Verify where you are with git branch --show-current. A merge affects the branch you have checked out, so this check matters.
5. Update the destination if needed. For a shared branch, you may want to incorporate its latest remote changes before merging. Run git pull --ff-only origin main, substituting the remote and branch names as appropriate. This updates the branch only when Git can do so by moving its pointer forward, rather than creating a merge commit. If this command cannot proceed, see Troubleshooting before continuing.
6. Merge the source into the destination. Run git merge feature, replacing feature with the source branch. Git may fast-forward the destination when it has no separate new commits, or create a merge commit when the histories have diverged. If Git reports conflicts, do not run another merge; resolve the current one as described below.
7. Review and verify the result. Run git status and inspect the changed files. Run relevant tests or checks for your project. You can view recent history with git log --oneline --graph --decorate -n 12. Confirm the intended changes are present on the destination branch.
8. Push the destination if it is shared. When the result is ready, run git push origin main, using the correct remote and destination branch. This publishes the merge for other users. A push may be rejected if the remote has advanced; fetch and review the new commits rather than forcing the push.

Common Mistakes

• Running the merge from the wrong branch: Git merges into the checked-out branch. Switch to the intended destination first, then verify it.
• Reversing source and destination: git merge feature while on main means “bring feature into main,” not the other way around.
• Assuming a merge publishes changes: A local merge changes your local repository. A push is needed to publish it to a remote.
• Ignoring uncommitted edits: Commit, stash, or deliberately discard them before merging. Avoid using destructive commands simply to clear a status message.
• Deleting a branch too soon: Keep the source branch until you have verified the merge and confirmed the project’s workflow allows cleanup.
• Using force push to solve a rejected push: A force push can overwrite commits on the remote. First fetch and understand why the histories differ.

Tips

• Use descriptive branch names and confirm them before commands that change history.
• Fetch before merging when working with other people, so you can see current remote branch information.
• Read the merge output. Git tells you whether it fast-forwarded, made a merge commit, or stopped for conflicts.
• For a merge commit message, Git usually opens your configured text editor. Save and close it to complete the merge; canceling the editor may leave the merge unfinished.
• Agree with your team on whether to use merge commits, fast-forward merges, or another workflow. The appropriate choice depends on how the project tracks shared history.

Troubleshooting

Git says local changes would be overwritten. Run git status to identify the affected files. Commit your changes, or stash them with git stash, then retry. If you stash, restore the work afterward with git stash pop; check for conflicts because restored edits can overlap with the merge.

Git reports merge conflicts. Run git status to list conflicted files. Open each file and look for markers such as <<<<<<<, =======, and >>>>>>>. Edit the file to keep the correct combined content, remove the markers, and save it. Then stage resolved files with git add path/to/file. After all conflicts are resolved, run git merge --continue if Git requests it; otherwise, completing the merge with git commit may be necessary. Run tests and inspect the changes.

If you decide not to complete the merge, use git merge --abort to return to the pre-merge state when possible. Check git status afterward and preserve any work you made during conflict resolution before taking further action.

The source branch is not found. List branches with git branch -a. If the branch exists only on the remote, fetch it first. You can check it out with git switch --track origin/feature, adjusting the remote and branch names, or merge the remote-tracking name directly when appropriate.

The push is rejected. The remote may contain commits you do not have locally. Run git fetch origin, inspect the difference, and integrate the remote updates using your team’s workflow. Avoid force-pushing unless you understand the consequences and have explicit approval.

Frequently Asked Questions

Which branch should I check out before merging?
Check out the branch that should receive the changes. Then name the branch you want to merge as the argument to git merge.

Does merging delete the source branch?
No. A merge does not delete either branch. Branch cleanup is a separate action after you verify the result.

What is a fast-forward merge?
It is a merge where Git can move the destination branch pointer forward because it has no separate commits to combine. Git updates the pointer without creating a merge commit.

Will Git always create a merge commit?
No. Git may fast-forward instead. If your workflow requires a merge commit, use git merge --no-ff feature, subject to your team’s conventions.

Can I undo a completed merge?
It depends on whether the merge has been pushed and whether new work depends on it. Before sharing, a reset may be appropriate, but it can discard commits. For a published merge, teams often use git revert -m 1 <merge-commit> to create a new commit that reverses its changes. Confirm the correct parent and coordinate with collaborators first.

Is merging the same as rebasing?
No. Merging combines histories and can preserve a merge point. Rebasing reapplies commits onto a different base and rewrites their history. Follow the project’s agreed workflow, particularly for commits already shared with others.

Related

• How to Save Twitch Streams: VODs and Clips
• How to Get the Most From Your Video Camera
• Physical AI System Design: Sensors, Models, Compute, Actuators