EBC Git Tutorial

This is currently under construction

Introduction

This tutorial aims at helping you to get started with version control using Git from an EBC-perspective. If you have suggestions on how to improve this tutorial, please make sure to bring this to our attention using the issue tracker. Don't be shy about this, if something does not become clear in this tutorial, it is likely not your fault, but a usability bug of this tutorial, so the issue tracker is a good place to talk about it.

The intended audience of this tutorial are students with no prior experience in version control systems, but we hope that it is also helpful for every interested reader.

Motivation: Why version control?

There are many good reasons for using version control and we couldn't agree more with Michael Tiller's What Engineers Need to Know About Version Control. We encourage you to take a minute and read that blog post. (Also, we like the image he uses to illustrate the dangers of not using version control.) In case you feel like tl;dr (which you shouldn't) here is quick summary of the main arguments for using version control:

• Danger: You can lose work by computer crashes or accidentally deleting/not saving. Version control helps to prevent that.
• History: Especially when writing a thesis or developing code (e.g. in Modelica or Python), many people make safety copies along the way, resulting in file names like thesis_2016-06-17_v4_corrected_final.docx (often followed by thesis_2016-06-17_v4_corrected_final2.docx...) or HeatingSystem_test-4_-new-control_valid.mo. Version control helps to prevent that.
• Collaboration: When working with others, we often waste time exchanging and adapting different versions of files. Version control provides a strong platform to manage collaboration better.

We hope these reasons are motivation enough to read on and learn how version control can help us to improve our workflows.

Understanding the concept

Unfortunately, before getting our hands on an example that demonstrates how to use Git for our version control we need to understand the concept of Git's version control system and introduce a few terms in order to make sure we speak the same language when talking about Git.

The repository

If your computer is running a Windows system, you are used to files being displayed in the explorer. For a local copy of AixLib, this may look something like this:

Let's imagine all these files at a specific moment in time (a "snapshot" of the entire file system within a given parent directory) to be represented by a blue dot that looks like this:

What a version control system like Git does is that it allows us to save, organize and manage many of such snapshots within a repository. We may visualize the concept of such a repository (or repo in short) like this:

Instead of just making changes (intentional or accidental) on the one version of the files that the explorer view offers us and hoping for the best, a version-controlled repo enables (and encourages) us to save such snapshots, giving us a timeline of changes that we can inspect and go back in, if we want to undo some changes. In addition, we can organize many of such timelines in parallel, allowing us to work in parallel with our colleagues or try out things with the confidence of knowing that we can always go back to a stable version saved in another snapshot. In Git, each of these parallel "timelines" is called a branch. A "snapshot" is called a commit. By default, there is one master branch. In projects like AixLib, we try to always have a stable version of our code on the master. Thus, all development and experiments are done in parallel branches (e.g. New feature 1 and Wild test 17b in the figure above). We can have a practically unlimited number of such branches in parallel, create new ones and delete others. In any case, we can always switch between branches, start new ones off our currently selected commit and merge our developments from one branch back into another (indicated by a green dot in the figure above). We will see how this works in a short time.

The big picture

You can use Git for version control on your local machine to better manage your files helping with the History issue mentioned above, but in order to also address the Danger of losing your work locally and to work in Collaboration with others, we will need to exchange data with a server. Let's use a similar visualization as introduced above to illustrate this concept:

Git is a centralized version control system. This means that your local computer as well as the server and any other computers working on a given project will have a full copy of the repo on their systems. If you are used to working with SVN (another version control system, but a centralized one), this is a notable difference. In Git, you can start new branches, save your commits and checkout alternative versions all locally without being connected to the server. This is great e.g. for working on a train without Wi-Fi, but we will have to keep in mind to actively synchronize our work with the server. We will get to this.

In addition to the repositories on your local computer and on the server, the figure above shows a part called "working copy". We will use this term to refer to what you are actually seeing in your Windows explorer like we showed in the first figure of this document. You will notice any Git repositories in your file system by a folder named .git in the top-level directory of the repo (you may have to tell Windows to show you hidden folders for this). When you checkout different branches from your local repo, the working copy will appear to "magically" change to the version that was last committed into this branch. It is absolutely important to understand how the working copy and the repository interact. Please note:

• If you make changes to your local files in your working copy, neither the repo on your local machine nor the one on the server are directly affected by this.
• Changes in your working copy have to be actively committed into your local repository.
• Changes in the working copy can be undone and any commit from the repo can be retrieved into the working copy.

Unfortunately, it will get just one step more complicated before we can start working with Git: We cannot directly commit from our working copy into the local repo. First, we have to stage all files we want to include in our commit. We are aware that this may seem unneccessary in the beginning, but you will get used to it and see that it makes sense in order to bundle different changes into different commits to make your history clearer and easier to understand and retrack.

Different servers

There are several options where the server repository may be hosted. Obviously, there is GitHub (https://github.com/). GitHub is probably the most popular service for hosting Git repos. All open-source projects are hosted on GitHub for free, closed-source projects have to be paid. We use GitHub for all our open-source projects like AixLib and TEASER (and there's always more to come!).

In addition, RWTH Aachen University runs its own Git Server called RWTH GitLab at https://git.rwth-aachen.de/. You can log in to RWTH GitLab with your TIM account, making it ideal for starting your own projects (e.g. for your thesis).

Another very important aspect about these Git servers is that they offer a web-view of your repository, integrating an issue tracker, pull requests, network-graphs and much more with your files.

Installing Git

If you are using your own device, you can simply download and install Git from https://git-scm.com/.

If you are using an EBC computer, please install Git using the Software-Center on your Desktop. It is listed as Software Freedom Conservancy - git.

Now you are almost ready to use Git for version control. For this tutorial we will use the command line. Yes, we know that some people will prefer a GUI and we will show you how to get started with a GUI at the end of this tutorial, but to understand the concepts and fall back on when the GUI is behaving strangely, we encourage you to bear with us and the command line. In order to make your machine understand Git, you have to add your Git installation (e.g. at C:\Program Files (x86)\Git\bin;) to the PATH environmental variable ("Umgebungsvariable" on a German system):

A simple Git example

For this example, we will use the RWTH GitLab Server. But if you have no access to that server, any other Git Server is pretty similar.

Creating a new project on the server

After logging in to RWTH GitLab at https://git.rwth-aachen.de/ we can start a new project by clicking on the green button:

We can then fill in project name, description (it says optional, but please always provide a description), chose a privacy setting and create the project:

At this moment, the repo is empty and exists only on the server. Using the visualization scheme from above, the situation is this:

Cloning the repo to my local machine

Now we want to start working with this repository. In a limited way, some Git platforms will allow us to modify files on their web interface, but usually we will want to have the repo locally and work there. Thus, we clone the repo to our local machine. To do that, we use the command git clone <server address of our new repo> in the command prompt (right-click on the image and chose "show image" for a larger version):

We do get a warning that we seem to have cloned an empty repository, but as this is what we expected, we will not worry about that. Instead, let's go back to the concept view to see what happened:

With git clone https://... we created a local repository that is linked to the server repo by the address we gave with the command. Now, the repo exists twice, on the server, and on our local machine. Also, the working copy that we can see in the Windows file system shows us the empty repo. we see a directory that is empty except for the .git folder, that indicates that this directory is in fact a git repo: