Guide to Merging a Git Branch into Master

In an earlier article, I showed you how to use git fetch, why it’s different from “git pull”, and under which circumstances it makes sense to use “fetch” instead of pull. With that background, we will now look at how to merge a git branch into the master branch. This operation is at the heart of the git workflow, and it’s where git’s power shines.

Scenario – Developing a Feature Branch

To understand what’s going on, let’s say that you’re in charge of developing a new feature in the application – for example, a new addition to the login form. You don’t want to develop this feature live in production, because that would mean that users would see incomplete, and possibly dangerous changes that don’t have validation. And, of course, if you make a mistake, you could bring the whole site down!

Logically, the best thing to do is to develop the feature locally on your machine, and then deploy it to production after you’ve tested everything and made sure that it works. To do this, you create a separate branch that we will call “feature-branch” in future code examples. All development on this new feature happens in feature-branch. When the time comes, we “merge” the changes you made in feature-branch into the main branch. It’s that simple!

Here are the complete set of steps you need to make the above happen:

1. Pull the most recent copy of the project onto your local machine
2. Create a new branch
3. Switch to the new branch
4. Work on the new feature, make changes and commit those changes
5. Switch back to the main branch
6. Pull the most recent copy of the master branch again
7. Merge the new branch into the master branch
8. Push your changes to the remote repo

Here’s a step-by-step explanation of how to accomplish each of the above steps.

1. Pull the Most Recent Changes from the Remote Repo

When creating a new branch to work on a new feature, getting the most recent repo onto your local machine is essential. This ensures that when the time comes for you to merge the changes you’ve made to your feature-branch, you’ll have as few conflicts as possible.

To do this, use the following command:

git pull origin main

To run this command, you need to have already created a git repo on your local machine and cloned a remote project. If you haven’t already done this, check out my earlier tutorial on how to connect your VPS to a git project and download a remote repo’s files.

Running this command, here’s an example of what you will see:

In this case, my local git repo is already up to date.

2. Create and Switch to a New Branch

The next step is to create a branch on which you’ll work on the new feature, and then switch to it to start working. We can do both with a single command:

git checkout -b new-feature

Here’s the output:

Now whatever changes we make will be restricted to the new branch only.

3. Make Changes and Commit Them

For this example, I’m going to make a change to a file called “file1”. It’s nothing special, just a change for its own sake. I will then add the file and commit the changes using the code below:

git add file1
git commit -m "Modify file1 in new-feature branch"

Here’s what the output of the above two commands looks like. I’ve added a single line to “file1”, representing the new feature on which I’m working:

As you can see, git recognizes that I’ve modified “file1”, in the new-feature branch and it’s added it to the list of changes to the project. So far, the main branch of the project “main” remains untouched. The changes I make here are restricted to the new branch alone. At any time, I can switch back to the main branch, and the changes to the “new-feature” branch will not show up over there.

Let’s say that’s the extent of all the changes we want to make. In a real feature release, of course, there will be a lot more files and folders that change. There will also be entirely new files and perhaps even folders created. In such a situation, we need to commit not just a single file, but all the possible changes that have been made. To do this, type:

git add .

The above command adds to the staging area all the changes that have been made within the current folder, as well as all the sub-directories. Once you’ve staged everything, you can commit the changes as usual.

4. Switching to the Main Branch

Now that we’ve finished working on our new feature in the “new-feature” branch, it’s time to merge the changes with the main branch. To do this, we first have to switch to the main branch and merge the new branch from there. To switch, we use the following command:

git checkout main

The above command leaves the branch on which you’re currently working and switches the context to the main branch. If you want, you can also use the “switch” command for the same purpose like this:

git switch main

We’ve written an article explaining the differences between the “switch” and “checkout” commands, but basically, the “switch” command is more specific. Any uncommitted changes will carry over to the new branch.

When you switch to the main branch, you’ll see that the file we edited in the previous branch no longer contains the changes we made while we were in the “new-feature” branch.

As you can see, there’s no reference to the changes I made, relating to the new feature.

5. Update the Main Branch

It’s always a good idea to first update the branch into which you’re merging because you don’t know what changes have been made since the last time you pulled from the remote repository. You don’t want to accidentally merge the new branch into an outdated version of the main branch. So always ensure that you have the most recent copy by using the following command:

git pull origin main

This will get the most recent copy of the main branch.

6. Merge the New Feature into Main

We’re ready to merge! Type the following command:

git merge new-feature

Here’s what it looks like:

As long as there are no conflicts, you can see that git merges the changes you made in the feature branch into main. You can see below, that the changes I made to “file1” in the feature branch are now available in main:

And you’re done!

7. Push the Updated Main Branch to the Repo

Finally, we need to ensure that we update the remote repo with the new feature. To do this, type:

git push origin main

This pushes the changes we just merged into main to the remote repo. Here’s the output:

And that’s how you merge a new feature into main.

Conclusion

Merging a git feature into main is pretty easy, once you understand the steps and why they happen the way they do. It’s one of the core workflows of git, and if you’re developing a project, you’ll be doing this so often, that it’ll become second nature very soon.