MRC/Tutorials/Git

Creating a software solution together means sharing a project, which in our case means sharing code. We will be using git for this. Git is "a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency":

• version control means that the files and changes you make to them are 'tracked' over time, i.e., their 'history' is stored. You can always go back to previous versions, show the differences between a certain point in time and now, and much more.
• distributed means that you don't necessarily need a central server to store your changes. Every team member has the full history available, and can always save his or her changes or go back to previous versions, even if he or she is offline. However, note that it is possible to use a central server that every team member writes his or her changes to, and receives the changes others made from. In this project, we will be using such a central server.

Clone a project

The examples you worked on up until now are stored on your own computer, which is fine if you are the only person working on your project. However when working with a team you need every member to have access to the most recent version of the code base. Well, sharing is easy in git! Your teammates can get a local copy of the repository. This is called 'cloning', and works as follows.

The MRC team has already initialized a git repository for you which includes a small example. To share the repository with your group we will use GitLab. GitLab is open source software to collaborate on code. The TU/e has its own gitlab server which we will make use of. Now:

- Browse to gitlab.tue.nl and click the TU/e login button - Take the steps you usually take to login to your TU/e account - E-mail your username (that starts with @) to Peter van Dooren (only one group member has to send their username) - Once we have added you to your group's project, you will receive an e-mail with the link to your repository - You can then add your colleagues to your project and start collaborating!

Before you can clone the repository we will have to tell gitlab it can trust your computer. For this we use a process called ssh. In a terminal type

ssh-keygen

Don't enter anything when given prompts. Simply press enter two or three times. We don't really need a passphrase for this ssh key and we can use the default location. After doing this type

cat ~/.ssh/id_rsa.pub

This will print your public ssh key to the terminal. Next, on gitlab select edit profile on your own profile. In the tab SSH Keys select `Add new key`. In the key field copy paste your public ssh key. (remember that in a terminal copy is done via ctrl+shift+C). Give your key a descriptive name such as "MRC-virtual-ubuntu" and add the key.

SSH is communication protocol. The keys we use are a way for computers to verify eachothers identity. When you communicate with gitlab on your virtualbox the computer will automatically authenticate itself with this key. Think of it like a password for computers.

Once you added your ssh key to your account you can clone your groups repository using the following command (fill in the your group name for <GROUP_NAME>, or copy the whole link from the GitLab page of your group):

cd ~/mrc

git clone https://gitlab.tue.nl/mobile-robot-control/2024/<GROUP_NAME>.git shared_project

This will create a directory called 'shared_project' in which you will find the files that someone else made. Now, this is your local copy of the repository to which you can make changes. We will learn here how we can save those changes and safely store these changes to the central server.

Telling git who you are

Before you start using git, you have to tell git who you are. That way, git can 'stamp' all the changes you make with your name and email address. That way it is easy to keep track of who did what, and when. Just run the following (with your real name and email address):

git config --global user.name "Put your name here"

git config --global user.email "Put your email address here"

Making and committing changes to a repository

Navigate to your project directory, which is most likely the directory you just created while cloning the repository. For this tutorial, we will use '~/mrc/shared_project', but you will use the actual name of your project.

cd ~/mrc/shared_project

Lets add the files of our previous exercise to this folder. Copy the folder exercise1 to your shared folder.

cp -r ~mrc/exercise1 ~mrc/shared_project/exercise1

Lets also make some changes to the README.md. Add your name to the list of group members. Open a file editor with

gedit README.md

After opening the file, make your changes and hit save.

If you want to check what changes you have made since your last commit use

git status

You will see a list of modifications and untracked files, e.g., something like this:

Changes not staged for commit:

(use "git add <file>..." to update what will be committed) (use "git restore <file>..." to discard changes in working directory)

modified: README.md

Untracked files:

(use "git add <file>..." to include in what will be committed)

exercise1

Modified means that the file has been changed since the last commit. Untracked means that these files and folders are not under git version control. If you do not remember what you changed since the last commit you can inspect it with

git diff README.md

This will show you the changes you made to README.md. If you leave out the argument git diff will show you the changes in every file in the repository.

Note that we only want some of the files to be tracked by git. For example, the bin and build folder are automatically generated by CMake and compilation. It is not necessary to share these files with your team members. We should therefore only add the source files, and the CMakeLists.txt (and possibly other files that you want to share). Since we know that we will never want to commit the build and bin folders we have specified these folders in a process called [gitignore](https://git-scm.com/docs/gitignore)

We should tell git which files we want to keep. To make sure git will keep track of files, use git add:

git add README.md

Now, run git status again. You should see something like this:

Changes to be committed:

(use "git rm --cached <file>..." to unstage)

modified: README.md

Untracked files:

(use "git add <file>..." to include in what will be committed)

exercise1

As you can see, you now have some 'changes to be committed'. Committing means we store the added files as they are now. From that point on we can make new modifications, and we can always roll back to this version, see the changes since this version, and, we can share the changes with others. To commit the changes:

git commit -m 'Type a meaningful sentence here'

The part after '-m' is the commit message. It is important that this message is a meaningful message that describes what the added changes are, for example 'fixed this-and-this bug' or 'added this-and-this feature'. That way, you can look in the 'git log' and easily see what was added when, and to which version you need to roll back if you have to. So, we have commited our changes. Let's see the status using git status. It no longer indicates changes to README.md. That is correct, we just committed them! Now, have a look at the git log:

git log

It outputs an overview of who committed what and when. You should see your name and commit message, and some long code with letters and numbers. This is a commit hash, and can be thought of as a unique id for this commit.