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: