Git and GitLab usage¶

Warning

Make sure that you have read the Git and GitLab Intro-section of this manual and followed the instructions in Software preparation!

Motivation¶

This part of the course explains how to use Git and GitLab for basic usage. While completing it, you will set up the Git and GitLab environments that are used throughout this course. You will be able to create a new repository, collaborate with other developers and execute day-to-day Git commands.

In our view it is vital to learn how to use Git on the command-line. Typing these commands by hand and evaluating the resulting messages will give you a deeper understanding of how to use Git. When using automatic and often graphic interfaces at a later stage you will benefit from this when debugging errors and understanding unexpected behaviour.

I hear and I forget. I see and I remember. I do and I understand. - Chinese proverb

To learn Git is to do Git. There is no way around it: you will need to use Git frequently to understand its workings and remember the different commands. The assignments in this document will help you on the way and provide some basic commands. We urge you to do these assignments and – even better – try other commands as well!

Introduction¶

Typically you would like to have to following order of events:

Double Quote

There is a dire need for the implementation of some idea. After some intensive brainstorm-sessions and the use of many sticky notes, a team of creative programmers is formed. It is decided which project management methodology to follow (Agile, Scrum, Waterfall etc. etc.) and to use GitLab for maintaining the code, documentation, issues, testing and deployment. The developers start to work systematically, implementing the specifications of the project management and within the expected timeframe the final program is ready for dissemination.

Yeah, right!

True, while writing millions of lines of code each year, which is business as usual in many big companies, this is the ideally preferred and envisioned course of program development. However, more often the writing of code in practice will be more along the following lines.

First iteration¶

For your research you would like to implement your idea, algorithm, service or whatever it may be on your computer and you start writing the first version of your program in a single file. After some time of saving the changes to the same file again and again it becomes hard to backtrack ideas or try out sidetracks. You solve this to some extent by timestamping the files. Unfortunately, this very soon results in a large pile of files making it hard to navigate and to keep track of the content of all versions. A much better solution is to use Version Control software and you decide to keep a record of these revisions by storing your file in a Git repository. Typically, this is performed by iteratively going through this loop:

$ git init
### LOOP
# write code in <file>
$ git add <file>
$ git commit -m "<comment about changes>"
### END LOOP

Note

Observe that in the above example git commands are given on the command line. It is very likely that writing the code will be done in a programming environment like Matlab, Spyder (Python), Visual Studio Code or any other IDE (or even a text-editor). Most of these programs have a convenient and often graphic method for Git management.

With git init a .git directory is created which will be used by Git to keep all repository related information locally. Storing the changes in files in the repository is in general a three phase process:

create or change a file
add this file to the staging area of Git
if satisfied with the status of all the files added to the staging area, the staging area is committed to the repository. Now a snapshot with the changes is stored in Git together with an identification code and potentially a few comments about the changes

Assignment

Follow the instructions below to learn how to create a repository and add a file to it. Note that the instructions are not always complete! More information about commands can be found in this manual, typing $ <command> -h (for help) or searching the internet.

open a terminal (on Windows Command Promp) and create the directory gittest
inside gittest create a Git repository with git init
first setup your identity in the global Git settings for future use. This has to be done only once on your computer:
```
$ git config --global user.email "<email address>"
$ git config --global user.name "<full name>"
```
create a file with some content and add it to the staging area with git add
inspect the status of your repository with git status
commit the staging area to the repository with git commit
again inspect the status
edit the file and change the content
inspect the changes in the file with git diff
add the file to the staging area and check the status again
reset the staging area and remove the additions to it with git reset and check the status
check what happens when trying to commit. Do you understand what’s happening?
now add the file (again) and commit it
inspect the log of the repository with git log to see all commits
keep this directory and the contents for future use!

Moving repository to server¶

Having only a local copy of your repository is not very safe and makes development on other computers impossible. This issue can be solved by moving the repository to a server. The repository can then be cloned to create a local copy on each computer that you use. To do so you first need to create a new project in GitLab. After that you must reconfigure the local repository on your computer to use the server for central storage and finally push the local repository to the server.

The GitLab server we will be using during this course can be accessed with this URL:

https://gitlab.ewi.tudelft.nl

Important

Make a note of this link as you will be using it frequently during the course.

Assignment

visit https://gitlab.ewi.tudelft.nl and login with your NetID. Create a password if this is the first time you login
create a new empty (blank) project:
name your project gittest and make sure that your username is selected in the Project URL dropdown menu:
some information is now shown on how to use the empty project that you just created. Read all information carefully, but for now only carry out the commands under Push an existing Git repository on your local computer to have your local repository use the GitLab server:
```
cd gittest
git remote rename origin old-origin
git remote add origin git@gitlab.ewi.tudelft.nl:<username>/gittest.git
git push -u origin --all
git push -u origin --tags
```
Note

While doing this you can disregard the warnings after the rename command. Change <username> to your GitLab username as selected in Project URL during the creation of the new project (use \ in case you used spaces in your name). Also, notice the .git extension; do not remove this!
your local repository is now using the GitLab server for central storage. With the last two git push commands all files in the repository are send to the GitLab server. Check this by clicking on the Project Overview menu-item (the icon of a little house) on the left-hand side of the GitLab page
also check the commits made in the previous assignment by clicking on the Repository→Commits menu-item on the left-hand side

Collaboration and cloning¶

Having the repository available on a central server will allow for other developers to collaborate with you on your code. Therefore, you will need to configure GitLab to allow other users to access your repository. This can be done with the Members menu-item on the left. After that the developers can clone your repository, make changes and push these back to the server. For the following assignment you will not actually add other members but you will learn how to clone an existing repository:

Assignment

For this assignment we will start with a clean slate and remove the local version of the repository on your computer created and used in the previous assignments. Do not worry! If you pushed your repository to the server if will still be there after removing the local version.

remove the entire repository on your computer by deleting the complete gittest directory
goto the GitLab Project overview page of your repository and click on the clone button on the right and copy the URL below Clone with SSH:
on your computer open a terminal and give the clone command using the URL from above:
```
$ git clone git@gitlab.ewi.tudelft.nl:<username>/gittest.git
```
most likely the URL will contain your username instead of <username>
as a consequence a new directory is created with the name of your repository. Go to this directory and check the status of the repository. Also, check the remote configuration with git remote -v
as before make some changes to (one of the) file(s), add them to the staging area and commit
finally, the changes are send back to the server with git push

Important

Actually, we have skipped an important step. Before every push you must always check if there have been other commits send to the repository since the last time you retrieved it yourself from the server. In this way any merging conflict will be solved before pushing your changes. This is done with:
```
$ git pull
$ git status
$ git push
```
Essentially, the pull command will retrieve the latest changes from the repository.

When you clone a repository the script with the loop at First Iteration changes somewhat into:

$ git clone <URL>
### BEGINNING OF THE DAY
$ git pull
### LOOP
# write code in <file>
$ git add <file>
$ git commit -m "<comment about changes>"
### END LOOP
$ git pull
$ git status
$ git push
### END OF THE DAY

We are very happy with for the Git flowchart below which illustrates all possible basic Git steps you will use in your daily life during our course and have used in the assignments so far:

GitFlowchart

Fork¶

Users … can “fork” [a repository] to create their own copy, push commits to their copy, and do a merge request from their fork back to the main project. This allows the owner to be in full control of what goes into the repository and when, while allowing contributions from untrusted users.

https://git-scm.com/book/en/v2/Git-on-the-Server-GitLab

We will use the fork utility in GitLab only for creating copies of the templates that have been provided. The merge request function will not be used.

In the remainder of this course you will use a new repository shared with one other student: your BFF for this course. One student will create the repository and invite the other student to join. The repository will at first contain exact copies of the labworks templates. In these templates you will find skeletons of code in which you will be working as a starting point. You are only permitted to change your own copy of this repository!

Your private copy is made by creating a fork of the template and then detach this fork. The new repository created as such must be placed in a subgroup with a descriptive name: <netid-student-1>_<netid-student-2>. Notice the underscore between the two NetID’s! The subgroup must be created in the group AP3132 - ADIP → 2020-2021. If for instance Sherlock Holmes with NetID shomes and John Watson with NetID jwatson share a repository this will be forked inside AP3132 - ADIP → 2020-2021 → shomes_jwatson. Because the forked repository will have the same name as the source repository (labworks) the full name of the forked repository will be AP3132 - ADIP → 2020-2021 → shomes_jwatson → labworks

For this course you will use one new repository per assignment shared with one other student. One student will create (fork) the repository and invite the other student to join. The repository will be an exact copy of the labwork template given. In your copy of this template you will find the skeletons of code you will be working on in the assignment as a starting point. You are only permitted to change your copy of this repository!

The copy will be made by creating a fork of the template and detach this fork afterwards. The new repository must be placed in a subgroup with a descriptive name: <netid-student-1>_<netid-student-2>. Note the underscore between the two NetID’s! The subgroup must be created in the group AP3132 - ADIP → 2020-2021. If for instance Sherlock Holmes with NetID shomes and John Watson with NetID jwatson share a repository this will be forked inside AP3132 - ADIP → 2020-2021 → shomes_jwatson. Because the fork will have the same name as the source repository (e.g. labwork_01) the name of this forked repository will be AP3132 - ADIP → 2020-2021 → shomes_jwatson → labwork_01

Important

It is important that the name of the subgroup conforms to <netid-student-1>_<netid-student-2> otherwise the labworks cannot be traced back to the right students and as a result cannot be graded!

Do not change the template repositories or the repositories inside other subgroups as this may result in loss of work or in delaying your fellow students!

Assignment

navigate in GitLab to the group AP3132 - ADIP → 2020-2021 via the top menu-item “Groups → Your groups. Because your account has already been added to this group it will be visible in your account
click on the New subgroup button and create your subgroup with the following name: <netid-student-1>_<netid-student-2>. Use the same name as Group name and Group URL
go back to the group AP3132 - ADIP → 2020-2021 via the breadcrumbs on top of the page:
verify that your subgroup is now listed amongst other groups
click on the title labwork_01 to open the template repository
create a fork by clicking on the Fork button that is located top right:
in the Fork project window select the subgroup you just created as the namespace to fork the project to by clicking on the Select button right of the subgroup
after a little time the new repository is created and shown. Verify that the path is correct via the breadcrumbs
now the fork relationship must be cut. This is done by clicking on the left menu-item Settings → General, scroll down to Advanced and click on the right on Expand. Scroll further down to Remove fork relationship and click on the button Remove fork relationship. After confirming you are ready with setting up your own repository for the labworks
for this course the fork relationship must be removed. This is done by clicking on the left menu-item Settings → General, scroll down to Advanced and click on the right on Expand. Scroll further down to Remove fork relationship and click on the button Remove fork relationship. After conformation you are ready with setting up the repository for the labworks in the course

You and your colleague developer can now clone this repository on your local computer using the commands explained in Collaboration and cloning to start working on the code.

This concludes this session about Git and GitLab. More information about these topics can be found on the internet. The following links will help you further along the road:

Last update: 2021-12-22