This document describes the preferred way to work together with several team members using git as a tool to enable this.

• 1. Content
• 2. Prerequisites
• 3. Steps
  • 3.1. Clone: getting all files locally on your computer
  • 3.2. Create a new (feature) branch
  • 3.3. Make changes and test them
  • 3.4. Commit your changes
  • 3.5. Use Rebase to include changes others made in your own branch
  • 3.6. Merge your work back to the main branch
• 4. Appendix
  • 4.1. Fast forward merge versus non-fast forward merge

1. As described in Home.
2. Install VS Code extension Git Graph.

1. From a internet browser go to the git repo on the internet. We'll use this as an example project: https://gitlab.com/xlrit/playground/example-project
2. Click Clone button an choose Visual Studio Code (HTTPS) Most Git repo's such as GitLab and GitHub have the ability to clone directly from their web interface to VS Code. If not you can simply copy the git link (in this example that would be https://gitlab.com/xlrit/playground/example-project.git) and then from VS Code [F1] > Git: Clone.
3. Choose the location on your computer where you want to clone your project to. We will choose C:\git as an example and click Select Repository Location.
4. You can now choose to open it in a new VS Code window or an existing one.

The result should look a bit like this (with just one file in it being the README.md file):

By default the current branch is called main (older projects still may use "master" instead of "main")

It is usually not a good idea that multiple persons are working in the same branch and that is the reason why you always start your work by creating a new branch. What you will be doing in that branch will then be completely seperated from other branches as well as the "main" branch.

1. From VS Code: [F1] > Git: Create Branch.
2. Give it a good but short name. In this example we will call it some_feature.

Preferred convention for feature branches is feature/name_of_feature.

It is recommend to set a default branch prefix like this: press CTRL+, and search for branch prefix. Set the Git: Branch Prefix to value feature/.

I won't tell you how, because that is up to you, but it will involve creating new files or changing/deleting existing ones.

One thing is really important and that is that you SHOULD TEST YOUR WORK AND ALL TESTS SHOULD BE SUCCESFULL!!. But because this is not about testing but working together we will only be change to just one file being the README.md file which should not break any tests. It should look a bit like this:

1. Click the Git icon. You should see something like this:

2. Enter some commit message and click the stage icon after the README.md file.

3. Click the commit icon (arrow 1) or press [CTRL+ENTER].

As this is the first commit for your new feature branch VS code will give you the option to Publish your new branch. After this first commit the button will change to Sync changes.

4. Click the Publish Branch button.

Changes are now saved online in the central repository (also called the "remote") so other can view your changes as well. Note however, that you are still working in a seperated branch which means that your work is still seperated from other branches (incl. the main branch). We'll come to that later. You can make more changes, test them, stage them, commit them and sync untill you are ready with your work, your "feature".

5. In the status bar of VS Code click on Git Graph. Your git graph should look a bit like this.

With "Rebase" we include all changes that others have added to the main branch since you created your own feature branch. It will make sure that your work does not conflict with others work and everything is still correct. This approach makes it:

• Easy to include work from others into your own feature branch
• Easy to merge your work back to the main branch after you are done with your feature,
• Easier to read/understand the commit history (as shown in the git graph).

Before you start you need to enable force push in VS Code. Do do that press CTRL+, (Settings), search for force push, and enable Git: Allow Force Push:

Follow these steps:

1. From the Git Graph window in VS Code click the Fetch From Remote(s) button. This will only get the info from the remote (but not synch the actual work locally). The result could look a bit like this:

Now you see different colors indicating different branches that actually have different commits in them. In this example 2 other commits have been added to the main (blue) branch in the mean time while your work is in the some_feature (pink) branch.

2. Right click on the description of origin/main then choose Rebase current branch on this Committ... and click button Yes, rebase.
3. Just click Dismiss ift there is an error message Unable to Rebase current branch on Commit. I simply means others have made changes in the same file and at the same location that you made changes (also called files with "merge conflicts"). Don't worry, that will probably happen a lot. In the next steps it is described how to resolve these "merge conflicts".
4. Resolve merge conflicts:
   1. Click on the Source control (Git) icon in the left black pane of the screen.
   2. And click on the file under Merge Changes (in this example that is just one file being the README.md file). Files under Merge Changes are files that have "conflicts".By clicking on them the file opens including controls that help you to quickly resolve any merge conflicts.

What you see is nothing more than a text editor but it also has controls to quicky accept different changes made to this file. Now the terms Current Change versus Incoming Change is really confusing because this is a matter of perspective. In this example "Current" refers to the changes you currently are working on, which are the changes you want to add to your own branch being the changes others have made to main in the mean time. As "Incoming" refers to the changes made to this some_feature branch before you were working on this "Current" change. Anyways, just think of them as titles that were given to these changes which you can accept or not.

3. Resolve all conflicts (all colored lines). You can use the Accept"... controls that VS Code gives you to quickly accept multiple lines (if you don't what to choose you can choose Accept Both Changes (which is the safest choice because that will keep all changes).
4. Save the file and click on the stage (+) icon after the file to stage it.
5. Repeat resolving the merge conflicts for all files under Merge Changes; when there are no more files, click the Continue button. This may cause new files to appear under Merge changes, in which case you have to solve these new conflicts as well.
6. When no more new files appear under Merge changes, you may need to test and/or change the file(s) to make sure that all still works and is as it should be.
7. Click the commit (✔️) icon to the right of SOURCE CONTROL to commit this Rebase.
8. Just close the COMMIT_EDITMSG to complete this rebase for the current commit. If you have another commit to process and that commit also has merge conflicts, you will get a git error here.
9. In that case simply repeat resolving the merge conflicts for all files under Merge Changes. Once you are fully done you should get a Sync Changes button. DON'T PUSH IT!! but use a "Force push" (as described below).

5. The final step is [F1] > Git: Push (Force). And press OK to continue. A Rebase is as if you started to work on your feature branch right after the 2nd commit from others. As this is not what actually happened you need to rewrite the commit history. Any rewrite of history requires a "Force push".
6. In the lower status bar of VS Code click on Git Graph. It should look like this.

_As you can see, it look as if you have just made the changes in a commit called some commit message based on the changes in a commit called 2nd commit from others.

In the example I just described you resolved just one change to just one file in just one commit. In reality you may need to repeat resolving and committing change you made in your some_feature branch. This is a good thing because any change you made may conflict with changes others made in the main branch and this is the right way to resolve this. It also makes clear that if possible, you should avoid making changes to the same file at the same location, but if needed you now know that it is not a problem and it can be fixed quite easily.

When you are done with your feature and you have tested everything you can now merge your work back to the main branch:

1. From VS Code \ Git Graph click the (Fetch from Remote(s)) icon. If changes have been committed to the main branch in the mean time, simply do another rebase as described in the previous section.
2. Double click on origin/main. This will checkout the main branch.
3. Right click on some_feature branch icon (NOT THE COMMIT MESSAGE) and choose Merge into current branch. You should get the following message.

4. Make sure the "Create a new commit...." is checked. This will create a non-fast forward merge as described in appendix Fast forward merge versus non-fast forward merge
5. Choose Yes, merge. Your Git Graph should look like this:

As you can see you have created a merge commit. This tells Git you want a special commit that does nothing more than add your work back to the main branch. You should also get a Sync changes button.

6. Click the Sync changes_ button. This will complete the merge.

With fast forward (where difference between main versus feature branch is not visible):

flowchart LR
    c1 -- feature --> c2 --> c3 -- merge back to main --> m

Without fast forward (where you can see the main versus the feature branch):

flowchart LR
    c1 -- main --> m
    c1 -- feature --> c2 --> c3 -- merge back to main --> m