Git

How many times have you written a document — an essay perhaps — where you think you have got to your final version and called it EssayFinal, only to read through it again and spot some errors, so you rename it EssayFinal2. Perhaps it’s a disserta- tion and you give it to your supervisor who has some comments so you end up with EssayFinalRevised. Perhaps you now realise it’s too long so delete some stuff and create EssayFinalRevisedCut. Then you read it again and realise that you really need to add something back from an earlier version as it no longer makes sense — Oh! Wait. . . Did you keep that earlier version?

Git is designed to deal with exactly this sort of situation. Unfortunately it doesn’t work that well with ‘binary’ files like the .doc or .docx files that Word uses, but for plain text files of the sort you use for writing programs and scripts, or files that you use with LaTeX, it removes these 2 sorts of problems completely. What’s more, you can synchronize git with Gitlab on the web giving you a backup of what you have done, allowing you to collaborate with others and to publish what you have done to share it with the outside world. Some journals (such as F1000) are even requiring that people who write papers describing code deposit it in Gitlab. If you write code to do your research, you can ensure that you tag your code in Gitlab with a version number so that when you publish your research you can tie it to a specific version of the code allowing you (and others) to recover exactly the version of code that was used to create your results.

Git and Gitlab are separate things, but linked. Git is the software that runs on your computer and manages your files. You don’t need to use it with Gitlab. Gitlab is an online platform that allows you to synchronise your local Git reporitory onto the web. You can also use Gitlab to browse other people’s repositories and download code or documents without ever using Git.

Git Installation

The first step we are going to take is to install Git on your computer. It's available for all platforms, just follow the instructions. When you are already familiar with Git or have a different client installed you can use that to follow along with the next steps.

Git Configuration

Now you have installed the git commandline-tool on your computer (verify by typing the following command in the git-bash command prompt: git --version) you need to configure your setup.

Configure the user

In a Git project all the changes you make will be tracked, to keep an eye on the author you have to configure the user. You use the commands below in the command prompt (On Windows in the Git Bash you installed).

Full name:

1

git config --global user.name "Your Name"

Email address:

1

git config --global user.email "your-hva-email@hva.nl"

You need to replace Your Name with your full name and make sure you use your HVA email address.

Git Repository

When you use Git, you create one repository for each program of project that you work on. You can start a Git repository on you computer or by cloning an existing Git repository from a Git service provider. There are many platforms which you can use (freely), like github.com, bitbucket.com or gitlab.com.

You can create projects yourself, but for IoT you can claim a repository on the GitLab server of the HvA from DLO, follow the next steps:

• Go to dlo.mijnhva.nl, and search for the course "IoT Individual Project - semester X" (where X is the current semester).
• Click on the contents-tab, and open the '🧰 Tools' section.
• Look for the page 'Gitlab project'.
• Press the button 'New project' and follow the instructions.

Now you should have a project (/repository) on the GitLab server of the HvA. You should fine this by going to gitlab.fdmci.hva.nl.

Git Repository: cloning

We are going to clone the repository we created on the previous step, but first we have to think about the placement of this (and other) projects on your computer.

Create a 'projects'-folder inside your home-directory and change your current directory to this folder:

1
2

mkdir ~/projects
cd ~/projects

If you have used SSH before you can use the SSH-command or set-up a key-pair yourself. Otherwise use HTTPS.

Clone your repository (using SSH, get your URL from the GitLab page of your project):

1

git clone git@gitlab.fdmci.hva.nl:...

Clone your repository (using HTTPS, get your URL from the GitLab page of your project):

1

git clone https://gitlab.fdmci.hva.nl/...

When you try to clone the above repository you will be prompted for your username and password:

1
2
3
4
5
6
7

Cloning into 'iot-XXXX'...
Username for 'https://gitlab.fdmci.hva.nl': XXX
Password for 'https://XXX@gitlab.fdmci.hva.nl':
remote: Enumerating objects: 3, done.
remote: Counting objects: 100% (3/3), done.
remote: Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
Unpacking objects: 100% (3/3), done.

Nice! You cloned your first git repository. When you visit this 'projects'-folder on your computer you should see an folder inside of it called 'iot-XXX'. Check if you can indeed find this folder.

Change your current working directory before you move on to the next chapter:

1

cd ~/projects/iot-XXX

Git commit

When you come across an important moment in your life you want to capture it, for example by taking a photo. In the world of Git you will be doing the same; you make snapshots of the contents of files you have stored inside your Git repository. This photos, or snapshots, are called commits.

Every time you make a commit, you save the progress up to that moment. That's the reason why it is important to make enough commits, so you can look back in time and go back to earlier moments.

Lets try to make our first commit, start by opening the 'README.md' file inside your Git repository on your computer. You should be able to open this file by using a simple text editor (notepad, Sublime Text, Visual Studio Code, ...).

The content of this file should look like:

1
2
3

# IoT Start Project

This is your IoT Gitlab project. You can use it to store your code and documentation. 

Try to add a new line to this file, for example:

1
2
3
4

# IoT Start Project

This is your IoT Gitlab project. You can use it to store your code and documentation.
This projects belongs to [Your Name].

Save the changes you made to the file and go back to the command line. We are going to make a commit, but first we have to tell which files we want to include in this commit.

Mark changes you have made to README.md as staged:

1

git add README.md

It's time to make our commit, when you make a commit it is important to also include a commit message. This helps other people (and your future self!) understand what and why changed were made. You can see this as the description of your snapshot.

Commit changes and include a commit message:

1

git commit -m "Added my name to the README.md file"

If we get the following output we are on the right track:

1
2

[main 3e3e3e3] Added my name to the README.md file
 1 file changed, 1 insertion(+)

This commit is now stored on our own computer or laptop, but in the next step we will look into how we can store this safely in the Gitlab environment of the HvA.

Git push

We can make commits, but those are still only available locally, on our own device. If we want to make sure are changes are available on the Gitlab website and to other team members we have to push our commits. Every time.

Start by looking into the status of our Git repository, we can use the status-command to display the state of the repository and staging area. It allows us to see the tracked, untracked files and changes.

1

git status

The output of this command should look like:

1
2
3
4
5

On branch main
Your branch is ahead of 'origin/main' by 1 commit.
  (use "git push" to publish your local commits)

nothing to commit, working tree clean

This means the server is behind us, we haven't pushed our commit yet. So lets do this now.

Push your commits to the remote server:

1

git push

The above command will output information about the progress, if it looks like this it's fine:

1
2
3
4
5
6
7
8

Enumerating objects: 5, done.
Counting objects: 100% (5/5), done.
Delta compression using up to 12 threads
Compressing objects: 100% (2/2), done.
Writing objects: 100% (3/3), 322 bytes | 322.00 KiB/s, done.
Total 3 (delta 0), reused 0 (delta 0)
To https://gitlab.fdmci.hva.nl/XXX
f7eea22..e19752e  main -> main

When you visit your Git repository on the Gitlab webpage you should see the change you made.

Git pull

When working in a team, or working on different devices, you won't get the commits from others automatically when they push. By using the pull-command you will pull in the changes from others, so you can make sure you only get changes when you are ready and nobody can interfere while you're working on something.

Because you are working on your own project, you won't have any changes from others. But you can try to pull in the changes you made on the Gitlab website. You don't have to try this now, but you can use the following command to pull in changes from the remote server:

1

git pull

Git conclusion

This workshop has given an overview of the most common things that you need to know when working with Git. Git is a extremely powerful tool and you can do a lot more with it than we have done here, but for most people this will cover almost all of your needs. Get into the habit of committing regulary, every half hour or so and whenever you have made any sort of significant change.

Now that you have completed this workshop, you can always click through to specific steps if you want to look back.

And remember: Google (or duckduckgo 🦆) is your friend.