MRC/Tutorials/Git

Creating a software solution together involves sharing a project, which, in our case, means sharing the code. For this purpose, we will be using Git. Git is a free and open-source distributed version control system designed to manage everything from small to very large projects with speed and efficiency.

• Version control means that all the files and changes you make to them are "tracked" over time, meaning their "history" is stored. This allows you to revert to previous versions, view the differences between any two points in time, and much more.
• Distributed means that you don't need a central server to store your changes. Every team member has access to the full project history and can save their changes or go back to previous versions, even if they're offline. However, it is possible to use a central server where all team members push their changes and pull the changes made by others. For this project, we will be using such a central server.

Clone a project

The examples you've been working on up until now are stored on your own computer, which works fine if you're the only one working on the project. However, when working with a team, every member needs access to the most recent version of the codebase. Sharing is easy in Git! Your teammates can get a local copy of the repository through a process called "cloning," which 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 for collaborating on code, and TU/e has its own GitLab server that we will use.

Here’s what you need to do:

1. Browse to gitlab.tue.nl and click the TU/e login button.
2. Follow the usual steps to log in to your TU/e account.
3. E-mail your username (starting with @) to Peter van Dooren (only one group member needs to send their username).
4. Once you're added to the group’s project, you'll receive an email with the link to your repository.
5. You can then add your colleagues to the project and start collaborating!

Before cloning the repository, you need to establish trust between GitLab and your computer this is done using a process called SSH. Follow these steps to set it up.

1. Generate SSH Key: Open a terminal and 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.

2. Retrieve Public SSH Key: Type the following command to display your public SSH key:

   cat ~/.ssh/id_rsa.pub

3. Add SSH Key to GitLab:

• Go to your GitLab profile and select Edit Profile.
• Navigate to the SSH Keys tab and click Add new key.
• Copy your public SSH key from the terminal (use Ctrl+Shift+C to copy).
• Paste the key into the Key field and give it a descriptive name, such as "MRC-virtual-ubuntu".
• Click Add key.

SSH is a communication protocol that uses keys to verify the identity of computers. When you interact with GitLab on your virtual machine, it will automatically authenticate using this key, similar to a password for computers

4. Clone the Repository: Once your SSH key is added, you can clone your group's repository with the following command (replace <GROUP_NAME> with your actual group name or copy the link from your GitLab group page):

   cd ~/mrc

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

This command creates 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.