git merge explained with simple examples [Beginners]

Git merge Introduction

Merging in git is the process of connecting forked history. That facilitates the joining of two branch histories into one main. When you finish working with all the relevant commits for your active repository, git allows you to merge all into the main branch. Git merge is simply the act of combining branches. Git usually seeks the unifying base among the two branches for successful merging to be effected. Without identifying the common ground git merging will cause an error or git conflict.

A successful git merge process will form a new commit merge. That implies that all previous commit histories will now create one main branch.

In this tutorial about git merge, we will explain the concept of git merge, the steps and merging examples, and handling git merge conflicts.

 

Syntax to perform git merge

You can check the official documentation to get the syntax of git merge:

git merge [-n] [--stat] [--no-commit] [--squash] [--[no-]edit]
	[--no-verify] [-s <strategy>] [-X <strategy-option>] [-S[<keyid>]]
	[--[no-]allow-unrelated-histories]
	[--[no-]rerere-autoupdate] [-m <msg>] [-F <file>] [<commit>…​]

 

Git merge workflow

Following image explains the workflow for get merge:

 

From the above diagram, if we merge my-branch into the main-branch, git will point the main branch to the last commit D. That is because both branches share a base commit. Also, the head will point to the main-branch as it is directly ahead of commit D in the sequence.

The new flow is diagrammatically illustrated below:

The above illustration is what is known as the fast-forward merging in git.

We can also merge  feat-branch  into the main branch which will alter the current history as shown in the following diagram.

From the diagram,  feat-branch is the active branch and it is pointing to the last commit E while the main-branch still points to commit D. The reason is simple, we haven’t merged the feat-branch into the main branch yet. Also, you will notice that my-branch isn’t visible anymore as we have merged into the main-branch.

To merge the feat-branch into main-branch, git employs a three-way merge process. Git will facilitate the merge basing on three conditions/snapshots to create one branch.

• Commit B which is the common connector
• Feat-branch most recent commit E
• Receiver branch(main-branch) recent commit D

See the process below:

 

For the three-way merging process, git is incapable of pointing directly to the last commit as it does in a fast-forward approach.

In the next section of this tutorial, we will further illustrate the git merging workflow using working examples.

 

Steps for merging in git

Apply the following steps for  successful merging  git without conflicts/errors:

## Switch to the branch to which you want to merge into.
## We will merge feature branch to main branch so switch to main branch
git checkout main

## Pull the latest changes from remote repo of respective branch
git pull
git fetch

## Merge feature branch into main branch
git merge feature

 

Setting up the lab environment

For you to implement git merge processes in your next project, you will first need to set up a working environment.

I have created a remote repo azure-test and cloned it to my local workstation windows 10 pro. azure-test will be our project of reference while running the git merge experiments for this tutorial. Here is the output after running the git clone command.

$ git clone https://github.com/git-testing/azure-test.git

Sample Output:

Since our git environment is now ready, we will start our practice for git merge as per the steps covered earlier.

 

Example -1: Merge a commit into main/master branch

Git allows you to merge a commit from a different branch into master/main. To merge a commit into the main/master branch you will run the git merge <commmit> command.

Using an example we will try to merge a commit from the feat-branch into master/main as shown below.

For a start, I will add a couple of files namely test-1.txt and test-2.txt in the feat-branch and then commit them. Next, we will run the git branch –a command to see how many branches that are in our active branch main/master.

$ git branch -a
  feat-branch
* main
  my-branch
  remotes/origin/HEAD -> origin/main
  remotes/origin/main

The output shows that we have two remote branches; feat-branch and my-branch apart from the main branch. It also points out the main/master remote branch.

The HEAD is pointing to the main/master which implies that it is currently the active branch. We will switch from the main branch to feat-branch to identify a commit that we are going to merge into the main branch.

First, we will run git checkout <branch name> as illustrated below:

$ git checkout feat-branch
Switched to branch 'feat-branch'

Next, we will run the git log --oneline command to see the commit inside our now active branch feat-branch.

$ git log --oneline
57dc89e (HEAD -> feat-branch) added another new file (commit-A)
aceab92 new file added(commit-B)
d044183 (origin/main, origin/HEAD, my-branch, main) Initial commit

Let us pick commit-A among the displayed commits then switch back to the main branch to finalize the process using git checkout<branch>command.

$ git checkout main
Switched to branch 'main'
Your branch is up to date with 'origin/main'.

Next let's run git merge <commit> command to finalize the process as shown below:

$ git merge <commit-A >

Sample output:

$ git merge 57dc89e
Updating d044183..57dc89e
Fast-forward
 test-1.txt | 0
 test-2     | 0
 2 files changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 test-1.txt
 create mode 100644 test-2

By placing commit-A - 57dc89e into the git merge <commit > command, we have successfully merged it into the main branch on our azure_test project.

 

Example-2: git merge branch into another branch

Git is a dynamic platform that you can rely on to make instant changes whenever necessary to your commits. Let’s say you have separate branches with commits and for some reason, you wish to combine them to improve performance. Git will allow you to merge the two branches into one and conveniently move forward in your project. Let’s use an example to illustrate the concept as follows;

First, we will run the git branch –a command to see all the branches in our local repo azure_test:

$ git branch -a
  feat-branch
  main
  my-branch
* test_branch
  remotes/origin/HEAD -> origin/main

Now that we have a display of all our branches, we will move forward with the experiment to merge two branches and understand how the process works. We shall try to merge the test_branch into my-branch in our local project azure_test .

It is important to first switch to the receiver branch my-branch as follows:

$ git checkout my-branch

Next we merge test-branch into my-branch locally:

$ git merge test_branch
Updating d044183..0b1dee7
Fast-forward
 test-1.txt | 0
 test-2     | 0
 test-3.js  | 0
 3 files changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 test-1.txt
 create mode 100644 test-2
 create mode 100644 test-3.js

According to the test results, we have successfully merged test_branch into my-branch.

Let us run the git status command just be sure:

$ git status
On branch my-branch
nothing to commit, working tree clean
User@DESKTOP-PFQIL78 MINGW64 ~/Documents/GitHub/zure-test (my-branch)

 

Example-3: Handling git merging conflicts

You will likely encounter a conflict if you try to merge two files with commits that affect the same section of that file. This is because git cannot figure out the correct copy to pick for the changes to be implemented before the merge.

 

How to identify git merge conflict

Git prompts

Git will promptly inform you whenever you encounter a conflict and the exact file with conflicting issues. Here is an example where I merged new_branch into the main/master branch after deleting a hello.js file from the head and kept the changes in new_branch.

Sample output

$ git merge new_branch
Auto-merging hello.js
CONFLICT (content): Merge conflict in hello.js
CONFLICT (modify/delete): error.js deleted in HEAD and modified in new_branch. Version new_branch of error.js left in tree.
Automatic merge failed; fix conflicts and then commit the result.

 

Using git status

Running git status command displays the current status and unresolved issues in your active branch including the conflicts. We will see how this works below.

Below are examples of common git conflicts

• Pending changes currently in our active directory will cause a conflict in case you merge without updating the changes
• Unresolved commit existing between the receiver branch and the merging branch

 

Steps for resolving git conflicts

1. Open the file with the conflict and manually resolve the issue
2. Run the git add command when through with the necessary change in the conflicting file so that the changes can be staged
3. Use git commit command to update the changes
4. Git will run the merge by introducing a new commit merge

You need to resolve a conflict by manually editing the file. You also need to delete the ‘<<<<<<<’, ‘=======’, and ’>>>>>>>’ in the file.

• <<<<<<<: Indicates the start of the lines that had a merge conflict.
• =======: Indicates separation of the two conflicting changes.
• >>>>>>>: Indicates the end of the lines that had a merge conflict.

 

Important commands for handling git conflicts

# git merge --abort
# git reset
# git diff
# git checkout
# git rest --mixed
# git log --merge

 

Summary

We have covered the following topics that will help you work well with git merge for your next project:

• Understanding git merge
• Git merge syntax
• Git merge workflow
• Steps for merging in git
• Git merge examples
• Steps for resolving git conflict
• Important commands for handling git merge conflicts

 

Further reading

Git-merge, git-merge-conflicts