6.3. How to work with branches and Merge Requests

6.3.1. Theory

All developments (bug fix or feature implementation) must be done in a dedicated branch, linked to a GitLab issue. Once the developments are finished, the branch is merged in the master after a review from other team members and eventually approved by dedicated approvers (configurable with GitLab). No changes should be pushed directly to the master. The complete development process is similar to the one described in this interesting article: a-stable-mainline-branching-model-for-git/

6.3.2. Practice

First, the GitLab issue must be created. The issue creation is described in How to work with issues.

Then, the dedicated branch can be created directly from the issue page, by clicking on Create merge request button. Check that option Create merge request and branch is selected.

temp_issue

This way, a branch with issue's number and name is created (from master by default but you can modify it to create a branch from another branch, although this is not recommended). The merge request is also created, but locked until the development is finished (with keyword WIP: in its title for Work In Progress).

On your local Git repository, you need to run a Git pull command, and then checkout this new branch.

Developments related to this issue can now be committed and pushed in this branch. Make sure all commits refer to the issue number in their message using "#'id-of-the-issue':".

Once the development is finished, the merge request must be unlocked. Edit the merge request, and click on Remove the WIP:

edit_merge

In Approvers, add team members who must approve your changes. If this is already configured project-wide, you don't need to add additional ones.

In Assignee, select who will finally decide to accept your merge. It is highly recommended to select Remove source branch when merge request is accepted.

After editing the merge request, click on Save changes button and people involved will be notified.

6.3.3. Branch merge & Conflicts resolution

During your development in your dedicated branch, another colleague will probably work on some other feature, or fix some issues, and will merge it onto master. Therefore, your branch will be outdated and a merge will be necessary. Furthermore, if you've worked on the same files than your colleague did on his branch, a merge-conflict will occur, and that's when problems arise... So there are 3 cases which can occur and with different solution.

6.3.3.1. Merge your branch into master

If you simply want to merge your branch into master, it is recommended that you do it using GitLab's interface. Actually, you shall not do the merge yourself, you shall assign your issue to a colleague who shall review it (see above for more details). Your colleague shall then:

  • Go to the merge request you were working on
  • Perform the review of the changes you did

NOTE: He can select which specific revision of the branch to compare with either master (by default) or another revision of your branch.

image

Once the review is finished, you can merge directly from the GitLab interface by clicking on the dedicated button.

6.3.3.2. Merge master into your branch

If you are working on a task which last long, you may want to upgrade your branch with the last changes available on master, either because of a bug fix, or to get a nice feature your colleague just merged onto it.

This can only be done locally, GitLab interface is of no use here.

The manual steps are described in Git's official documentation (French version here)

To summarize:

$ git checkout 'your-branch'
Switch to your branch
$ git merge master
Will merge the master into your branch

6.3.3.3. Solve merge conflicts

Solving merge conflicts can be very tricky sometimes.

GitLab can support a little for "basic" conflicts, but most of the time you will end up solve these conflicts manually.

To do so, a few tool and hints be can helpful.

A nice and free diff/merge tool is p4merge, from Perforce. It allows you to do a 4 view diff, which is very interesting in this particular use case.

  • TortoiseGit proposes to edit each conflicts by clicking on "Resolve...". This will open a window with the list of conflicts to solve. However, solving the conflicts may not be obvious depending on the text editor you configured with Tortoise. Using Beyond Compare 4 for example opens 2 files but not the correct ones, so you can't fix anything...

  • Git Bash, the default Git client for windows, allows you to configure some interesting tooling:

  • Once you have executed the git merge 'branch-to-merge' command and that you have conflicts to solve, you can use the git mergetool command
  • Depending on your Git configuration, you may not have registered any merge tool. To do so, you need to configure either your global .gitconfig file (normally stored in C:\Users\'your-user-name' or your local .git\config file.
    • Add the following in your Git config file, adapt the path if necessary:
[diff]
    tool = p4merge
[difftool]
    prompt = false
[difftool "p4merge"]
    cmd = \"c:/0_Softwares/Perforce/p4merge.exe\" "$(cygpath -w $LOCAL)" "$REMOTE"

[merge]
    tool = p4merge
[mergetool]
    prompt = false
[mergetool "p4merge"]
    cmd = \"c:/0_Softwares/Perforce/p4merge.exe\"  "$BASE" "$REMOTE" "$LOCAL" "$MERGED"

If you prefer to use Beyond Compare 4, you need to add the following:

[diff]
    tool = bc4
[difftool]
    prompt = false
[difftool "bc4"]
    #use cygpath to transform cygwin path $LOCAL (something like /tmp/U5VvP1_abc) to windows path, because bc is a windows software
    cmd = \"c:/program files/beyond compare 4/bcomp.exe\" "$(cygpath -w $LOCAL)" "$REMOTE"

[merge]
    tool = bc4
[mergetool]
    prompt = false
[mergetool "bc4"]
    #trustExitCode = true
    cmd = \"c:/program files/beyond compare 4/bcomp.exe\" "$LOCAL" "$REMOTE" "$BASE" "$MERGED"

Once you have finished to solve the merge conflicts, you shall commit/push as usual.

⚠️ NOTE: There are plenty of configuration option available on Git. You can have a list by entering the following command: git config --help

6.3.4. Work with modifications for multiple commits

Sometimes, you work on your branch, you have done some modifications at a file which target different issues. It is possible to use only some modifications in one commit and the others in another commit.

To work with that, "Git GUI" can help you:

  • Go in your Git directory, by example EGOS_Project, then you can run "Git GUI" by right click and select it:

    gitgui

  • If you are not familiar with "Git GUI", in the left hand corner (red section), the modified files are listed (blue icon for modified files which are already tracked and white for modified files which are not tracked yet). You can add a file to a new commit by clicking on its icon.

    gitgui_2

  • If you click on its icon, it will add all the file modifications to the new commit.

  • If you only want to add some modifications to the commit, you can see on the right the modifications done on the file, select the modified lines and right click to select these lines for commit. It will only add these modifications for the new commit.

    gitgui

  • The file is now listed in the staged changes (green box).

You can now edit your commit message:

  • The first line is to indicate the #issue number then what is the purpose of this commit,
  • The second line is to add more details on the commit,
  • Then, click on the sign off button to add your signature to the commit,
  • Finally, click on the commit button.

gitgui_3