MRC/Tutorials/Sharing your project through git

Introduction

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 version, show the difference since a certain point in time, etc.
• 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 stored his changes and go back to previous versions, even if he or she is off-line. However, note that we will use a central server every team member stores his or her changes to, and loads the changes others made from.

The first part of the tutorial shows how to initialize a git repository and how to store your local changes to the server. However, imagine that this may soon become a mess if every team member will do so. Therefore, it is advised that only one team member actually runs all the commands in this tutorial, but it is strongly recommended for the others to also take a good look and understand the different steps and commands.

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"

Intializing a git repository

Navigate to your project directory. For this tutorial, we will use '~/emc/my_project', but if you renamed your project in the meantime (which is actually advisable), use that name instead.

cd ~/emc/my_project

Turn the directory into a git repository:

git init

It's that easy! Now let's have a look at the current status of the git repository. Run:

git status

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

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

	CMakeLists.txt
	bin/
	build/
	src/

Untracked means that these files are not under git version control. 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. We should therefore only add the source files, and the CMakeLists.txt (and possibly other files that you want to share). To make sure git will keep track of these files, use git add:

git add src CMakeLists.txt

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

Changes to be committed:
  (use "git rm --cached <file>..." to unstage)

	new file:   CMakeLists.txt
	new file:   src/example.cpp

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

	bin/
	build/

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 any changes. 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.

Storing your changes on the server

Alright, you work is now safely stored on your computer. You can make changes, and commit these as well (remember, first use 'git add', then 'git commit'). But you also want to share these changes with your team mates!

Well, we have put up a git server such that you can store your projects in a safe place. You should have received an email with a username and password. Now:

• Browse to http://roboticssrv.wtb.tue.nl:8800/
• Log-in using the username and password you received
• Change your password: Profile (upper-right corner) -> Password (tab) and make sure to tell your team mates!

You are logged into 'GitLab', a very nice open-source git server that allows you to create new git repositories and manage them through a web interface. You won't have to use it much. Just now to create a new repository. To do so (while being logged in):

• Click on 'New Project' (the 'plus' icon in upper-right corner)
• Set the project name
• Leave visibility level to Private
• Click 'Create project'

That's it! You have create a repository on the server. We can now push the local commits you made so far to this project. Once we've done that, the commits are also safely stored on the server. So, let's do this!

First, we need to tell git where it has to store the commits. The online git project you just created has unique URL. This URL depends on the name of your project you created in GitLab. If your group number is 1, and the project was called 'my_project', you can set the URL of your local git repository as follows:

git remote add origin http://roboticssrv.wtb.tue.nl:8800/emc01/my_project.git

So, we've told the git repository where it should send the commits to (and where it can pull them from later). But we still have to tell git to actually send them there. This is called 'pushing'. The first time you push commits to the server, you have to use this command:

git push -u origin master

and enter your username and password (emc... and the password you received in the email, if you did not change it yet).

We won't go into details here, but the command basically states that the current commits should be send to the origin (of which we set the URL above) and that the git repository should 'keep an eye' on what happens on the server. This means that if one of your team mates also pushes commits to this address, we can 'pull' them to your local repository. This is exactly how the synchronization works. You push your changes, and pull changes that others made.

Now, make a small change to one of the files. Then if you run 'git status', you will see which file was modified. If you type 'git diff' you can see the actual changes. Quite useful, isn't it!

Again, you can commit the change once you've done something useful, but first you need to tell git again which files you want to commit by using 'git add'. Then once you've created the commit, you can push it to the server, this time simply using 'git push'. So, to sum up:

1. Make your changes
2. Add the files of which you want to commit the changes:

   git add ...

3. Commit your changes:

   git commit -m '... message ...'

4. Push your changes to the server:

   git push

   (the '-u' stuff is no longer necessary)

Share a project

Up until now, you have seen how you can commit your changes to the server, but it is not very useful if you cannot share your changes with your teammates. Well, sharing is easy in git! Instead of creating their own project, they can get a local copy of the repository you created in GitLab (and to which you pushed your local commits). This is called 'cloning', and works as follows (change the URL to the correct project url)

cd ~/emc
git clone http://roboticssrv.wtb.tue.nl:8800/emc01/my_project.git shared_project

This will create a directory called 'shared_project' in which you will find the files that someone else committed. Have a look at the git log, and you see who committed what.

Now, this is just a normal git repository to which you can make changes, commit and from which you can push your commits to the server. It is advised that one person in the group creates a project and corresponding git repository, and that the others clone it.

One thing is not yet explained, and that is how you can get the changes that others pushed to the server since you cloned it. Well, it's easy:

git pull

This will 'pull in' the latest commits and your files will be updated accordingly. Note that this won't work if you have modified files, i.e. file changes that you have not yet committed. You don't want these changes to be overwritten by a 'pull', so git doesn't allow it. To get the latest changes, you have to commit your changes and try pulling again.

Recap

The tutorial above showed how to create a repository in Gitlab, how to push changes to it, and how to pull changes from it. From now on, keep working in this directory and commit all your changes, and pull the changes from your team members.