Table of Contents
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
To merge the
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
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-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
$ 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;
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
$ 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 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 >
$ 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
commit-A - 57dc89e into the
git merge <commit > command, we have successfully merged it into the main branch on our
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
$ 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
my-branch in our local project
It is important to first switch to the receiver branch
my-branch as follows:
$ git checkout my-branch
Next we merge
$ 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
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 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
$ 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
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
- Open the file with the conflict and manually resolve the issue
- Run the git add command when through with the necessary change in the conflicting file so that the changes can be staged
- Use git commit command to update the changes
- 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
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