Using Merge Requests and Feature Branches in your Git Workflow

Introduction

Multiple developers contributing to the same master branch of the same repo is asking for trouble. The dreaded merge CONFLICT will surely occur. Merge conflicts happen because multiple developers modify the same file at the same time. Git is not able to choose the correct version.

One way to minimize merge conflicts and improve the Git workflow is to use feature branches and merge requests. This tutorial demonstrates one way to do that.

Prerequisites

Here are the prerequisites for this tutorial:

• All collaborators have GitLab accounts with appropriate SSH access.
• This tutorial uses a GitLab repo called acme-corp.
• The default branch of the repo is called main, but yours might be master.
• One collaborator has the Maintainer role. This person sets up the repo.
• All other collaborators have the Developer role.
• All developers and maintainers have a terminal application on the local computer with Git installed.
• All developers and maintainers have a basic knowledge of git and bash commands.

Step 1 - Protect the main branch

The Maintainer prevents developers from directly committing to the main branch:

• From a web browser, the Maintainer logs into the GitLab account and goes to the acme-corp repo.
• Click Settings > Repository.
• Expand Protected branches.
• Scroll down and ensure that the main branch is protected. Only maintainers should be allowed to push and merge to this branch.

Step 2 - Developers create feature branches

Developers cannot commit directly to the main branch. Instead, they create and work in feature branches:

• Open a terminal on your local computer.
• Clone the acme-corp repo.

• Complete the following steps:
  

  $  # go into the repo folder
  $  cd acme-corp
  $
  $  # make sure the repo is clean
  $  git status
  $
  $  # get the latest changes from the remote GitLab repo
  $  git pull origin main
  $
  $  # create a feature branch off of main and switch to it
  $  git checkout -B my-new-feature
  $
  $  # work in the new feature branch
  $  echo "my new file" > newfile.txt  # an example
  $
  $  # see the status of your new feature branch
  $  git status
  $
  $  # add and commit local changes to the feature branch
  $  git add .
  $  git commit -m "changes to my feature branch" . 
  $
  $  # push the new branch to the remote GitLab repo
  $  git push origin my-new-feature
  $
  

• From the browser, refresh your acme-corp repo in GitLab.

• Find the new my-new-feature branch in GitLab.

Step 3 - Developers create merge requests

Developers create merge requests to merge feature branches back into the main branch:

• From a web browser, the developer logs into GitLab and goes to the acme-corp repo.
• In the left sidebar, click Merge requests.
• Click the Create merge request or New merge request button.
• Add a Title and Description for the merge request.
• Click the Create merge request button.
• The developer monitors the merge request while it is in Open status.
• The developer checks the merge request for any warnings about existing merge conflicts.

Step 4 - Maintainers review merge requests

• It is the responsibility of maintainers to review, accept, and reject merge requests. Do this from the web browser, in the GitLab Merge request area.
• Use the Merge request area in GitLab to start discussions, view code differences, comment on code, etc.

• Maintainers should reject merge requests that:

  • Contain errors
  • Contain merge conflicts
  • Do not follow coding style guidelines

• Maintainers should approve and merge feature branches that contain correct code that follows coding style guidelines.

Step 5 - Developers update or delete feature branches

• If the maintainers reject the merge request, update the local feature branch:

  • Review the merge requests comments in GitLab.
  • Make the appropriate changes to the local my-new-feature branch on your computer.
  • Add and commit the changes locally.
  • Push your local feature branch to the remote repo in GitLab.

• If the maintainers approve and merge, then delete the local feature branch from your computer: git branch -D my-new-feature

Congratulations! You have used a feature branch and merge request to update your main branch. Use this technique to minimize merge conflicts, facilitate simultaneous work among team members, and protect the main branch.

Thanks for reading!

Follow me on Twitter @realEdwinTorres for programming tips, software engineering content, and career advice. 😊