0. Introduction

Do this tutorial with a colleague

This tutorial is for a pair (or small group) of colleagues to do together. It is not for one person to do alone. There are many other Git tutorials on the internet for one person to do by themselves.

This tutorial guides you and your colleague through a set of Git activities in three different user interfaces: web UI, VSCode, and command line. You should do all the activities in all of the user interfaces. Doing just the first few activities in the web UI will not be enough of an introduction for you to be able to work competently as part of a software development team.

Why Git?

Version control systems are the technological foundation of software engineering teamwork. They are how multiple team members all work together on the same code.

Git is a popular and powerful version control system. Version control systems are the most important teamwork tool in software development: There are many version control systems. We are using Git because it is popular and powerful. It is not the most user-friendly tool. You will find it frustrating at times, as everyone does. Ask for help when you get stuck.

Why not Dropbox, Google Docs, Notion, Office365, etc?

There are now many tools for collaborative document editing or document sharing. It is possible to use them for collaborative code editing, but they are not optimized for this purpose. No professional software teams use these tools for code version control. Three key features of code version control systems include:

Names for every revision of the software. So you can always switch to a specific revision. Git uses hashes for naming revisions.
Merge strategies for managing multiple variants of the software.
Conflict resolution strategies for when different programmers make different edits to the same lines of code.

1. GitLab Web UI

Git is a command line tool. Many people confuse Git the command line tool with the commercial website GitHub.com. The GitHub.com website provides additional functionality on top of the Git command line tool. GitLab is open source website software that offers similar functionality to GitHub. The University of Waterloo runs its own instance of the GitLab software at https://git.uwaterloo.ca, which we will be using.

You do not have to install any software on your computer to use the GitLab web UI, so it is a good place to start. When you use the GitLab web UI, you do not have a copy of the files on your local computer. To do more significant software development you will need to have a copy of the files on your local computer, which you will set up after you complete these web UI activities.

Sign up or Log in to GitLab

Go to https://git.uwaterloo.ca/
Log in to your account

Your screen should look like this:

Creating a project

To create a new project follow the following steps:

Click on New Project>Create blank project
Enter project name and select your project visibility (private/public etc.)
Click Create Project.

Adding your partner to your project

Click on the members tab in the sidebar to the left, and add the user ID of your partner. Give them Maintainer access (the second-highest level). Maintainer access is required to push to the main branch.

Adding your first file

To add a new file go back to project overview tab and click on the button 'New File'. Click the green 'New File' button again under the heading “Make and review changes in the browser with the Web IDE”. Enter a new filename (anything you want) and click the green Create File button.

Helpful Web IDE tabs

Committing and Branches

If you would like to edit and commit (committing is like saving) your changes on the web IDE of git, you can press the Web IDE button on the project overview page.
Here, you can edit the new file that you have made, and then "commit" the edit that you have made.
Pressing commit will initialise the initial commit of this file.
Click commit to master to have your initial commit added to the master branch.

Making commits one at a time (therefore no conflicts)

Now say you and other members of your project (here Tara and Giselle) wish to make changes to the project on the web IDE. The first case you will encounter is when the changes are done one at a time so there are no conflicts.

You can test this out as shown:

Tara makes a second commit:
Then Giselle deletes Tara's change and replaces it with her own test. The changes are shown on the screen before final commit:

If you would like to view the Commit History of the project, you can view it by clicking on the word Commits under the project title on the project overview page

Git Color coding

Any changes made in any file in the repository will be colour coded. Additions will be shown in green whereas deletions will be shown in red. This allows you to review your changes to each file before committing the change. You will have the choice of committing your changes to the master branch or creating a new branch with your changes (recommended if working with other persons on a project).

This also applies for using VSCode for version control, this does not however apply to using the Command line for version control. In the command line it will be shown as regular text but will say who made what changes.

Simultaneous Commits: same time, but compatible (no conflict)

If Giselle and Tara decide to add different lines of changes to the file and try to commit at the same time, what do you think will happen? Lets find out:

On Tara's Screen:

On Giselle's Screen:

When both press commit, we see that Giselle's commit goes through first. But Tara has also already made her change on that version of the branch that does not have Giselle's change. This means that Tara's branch is behind the recent commits and she has to create a new branch and then merge it into the master branch.

She sees the following:

So after clicking 'Create new branch', she creates a merge request to merge the new branch back into the master:

To see the merge request, click the Merge Request tab on the left sidebar.

To see changes being made in the merge request go on the changes tab

You can also see the commit history of this branch by going on the commits tab.

If you choose the cherry-pick tab you can cherry pick what changes you want to save and what you want to discard. If you are unhappy with the all of the changes you can use the revert button:

Upon accepting the merge request, The final document now looks like:

Note

This only happens in the Web IDE and the procedure is different in the VSCode interface and the Command Line. We will get to that in a bit.

Simultaneous Commits: same time with conflict

If Giselle and Tara edit the same line in the file and try to commit at the same time, what do you think will happen?

Merge conflicts occur when Git is unable to automatically resolve differences in code between two commits such ass when changes in the code occur on the same lines. This is because git does not know which code to keep and which to discard. It can occur when merging a branch, rebasing a branch or cherry picking a commit.

Tara:

Giselle:

If Giselle and Tara try committing changes to the web IDE at the same time one of the requests will go through first and the other will have to deal with a merge conflict.

After the new merge request was made by Tara (because she was late again) a merge conflict appeared because we tried to edit the same line.
Go to resolve conflicts and you can decide which of the conflicting changes you would like to keep or discard. The changes chosen will be re-committed.
After you press commit to the source branch you must press the merge button to merge into the master branch.
The final commit history will look like the following:

2. The VSCode Environment

Setting up the Development Environment

It is recommended that you install git on your local machine so that you can use it offline. There is no installation required for the Web IDE as it only requires you to sign in using your Waterloo credentials. If you would like to use VSCode you are required to also install git on your computer, a helpful link for installing VSCode can be found here and for installing Git here. Git must also be configured before you can use it, here is a helpful link to get that started. To use git on your Command line you must use the command line option available on your Operating System. For Mac and Linux users you can use your built in terminal by searching terminal and check your git version using the git --version command which allows you to see if git is installed properly on your device. For Windows users you can access your command line by typing the command cmd in the taskbar. If you still need more help you can visit this helpful link to get started.

TL;DR

If you would like to work in VSCode you must first install both VSCode and git on your computer. Here are some helpful links to get everything installed:

Downloading VSCode:

https://code.visualstudio.com

Downloading git:

https://www.atlassian.com/git/tutorials/install-git

Setting up your Repository in VSCode

Here are some steps to get your repository set up in the VSCode environment:

Cloning your Repository

After installing VSCode, you must clone your repository to begin working on it in VSCode. To get the repository URL you can go to the project overview page in gitlab and click on the clone button to clone with HTTPS.
If you have the option to "Open in your IDE" you can click on that which saves you the trouble of cloning the repo in VSCode.
If not you can paste the HTTPS into VSCode to copy the repository. Do this by typing Ctrl+Shift+P, and typing in Git Clone and selecting that option. Afterwards, paste the HTTPS and select clone with url.
After pressing enter you must select the repo location such as Desktop or Documents folder. VSCode will then give you the option to open the repository. You will then be able to see all the files in the repo, edit and create new files as well.

Creating new files and opening previously created ones

Tara right clicks to make a new file and names it Tutorial2.

Git Markers in VSCode

The markers above may appear next to your files in your repository in VSCode, these are their meanings and here is a helpful link to find out more about these markers and their uses:

https://stackoverflow.com/questions/48304195/what-are-the-u-and-m-file-markers-in-visual-studio-code

The Source Control Tab and Staging, Pushing & Pulling

If you go to the source control tab you can see the changes made to the repo.
Right click on the change and select stage changes.
When you press the check mark at the top of the source control tab it allows you to commit your changes and add your commit message and press enter.
After committing your changes you need to push your changes to the server. Click on the 3 dots in the source control tab and click push. When you press commit it commits your changes to your local repository but your changes are not seen to other members of the repo until you push your changes to the server.
Giselle will first have to pull the changes to see Tara’s commit (a new file called Tutorial2)
Now that the changes have been synced the two VSCodes will look like the following:
You can also press the sync button at the bottom of the screen to simultaneously push and pull changes.

Git Markers in VSCode

Every time you edit a file remember to save the file so that it shows on the source control tab as changes.

Tara edits the file tutorial2, she then saves the file and you can now see that the source control tab now shows the one change that is there.

Tara stages and commits her changes and then Giselle pulls.

Non-Conflicting Simultaneous Commits

Tara changes line 24 and Giselle changes line 20 simultaneously. After you stage your changes you can see your changes in a side by side comparison view by clicking on the Tutorial2 file in the Staged changes.

Side by side changes on each device:

Giselle now stages her change, commits it and then pushes the change.

After this, Tara tries to commit and push her change as well but is not allowed to:

So she then tries to first pull-You can now see Giselle’s change on Tara’s screen and the sync button now shows 2 outgoing changes.

She can now push so that Giselle can see her changes as well.

MORAL OF THE STORY, IN A NON CONFLICTING COMMIT ALWAYS PULL BEFORE PUSHING.

Conflicting Simultaneous Commits

In the VSCode Environment:

Tara and Giselle each edit the same line in their remote directory, note that this does not yet affect the code in the server because it has not been pushed yet.

If Tara and Giselle decide that they each want to change the same line in their remote directory, what do you think will happen?

Giselle’s Change:

Tara’s Change:

Giselle commits and pushes before Tara so her changes are logged by the server.

Tara tries pushing but she can’t so she first pulls and when she goes back to her tutorial2 file she sees the following:

So now Tara is given a choice between the versions that will be merged into the master branch. She is given options to accept the incoming change, accept current change, accept both changes and compare changes (found above <<<<<<< HEAD (Current Change)).

She wants to compare changes and so she chooses that option, this is what she sees:

Going back to the original file she decides to accept the current change and saves, stages the merged changes and merges to the server.

so the final file looks like:

3. The Command Line

Terminal, Command Prompt or PowerShell

Cloning existing repository

To open up the terminal in VSCode, at the top of the screen in VSCode, click Terminal, and then New Terminal. This should open a window at the bottom of VSCode with a line where you can type commands. This line where you can type should have a filepath in front of it, showing the directory you are currently in. You can navigate through the command line to different directories with the command "cd <filepath>". You should be able to navigate to the filepath where you want to clone your repository, and then type "git clone <HTTPS link to repository>" to clone your repository there.

Some other useful commands within the terminal:

"cd ..", which brings you up a level in your current directory.

"ls", which lists all non-hidden files in your current directory.

"cd <folder name>", which goes to the directory within your current directory with the specific folder name you entered.

Useful Git Commands

After your repository is cloned, navigate to your repository within the terminal. From this terminal, we can do git commands such as:

"git status", which shows the status of your current branch
"git pull", which pulls changes onto your current branch
"git add <filename>", which stages changes to be committed
"git add .", which stages all changes to be commited
"git commit", which commits your changes, then opens vi within the terminal so you can type in a commit message. To type in a message, type i, then your message, then press escape, and type ":wq"
"git commit -m <message>", which commits your changes with a message
"git push", which pushes your changes

Using these commands, you should again try to push some commits and deal with conflicts that may arise as previously.

Helpful Command Line Documentation

https://confluence.atlassian.com/bitbucketserver/basic-git-commands-776639767.html

Terminology

https://www.javatpoint.com/git-terminology

Related articles

Page:

Git (Basics of Source and Version Control)

User	Last Update
Mayurakhi Khan	1267 days ago

Browser not supported