1.7. Using Gitlab


1. GitLab

"Git is a version control system for tracking changes in computer files and coordinating work on those files among multiple people. It is primarily used for source code management in software development, but it can be used to keep track of changes in any set of files. As a distributed revision control system, it is aimed at speed, data integrity, and support for distributed, non-linear workflows."  Source : https://en.wikipedia.org/wiki/Git

GitLab is basically a web-based Git repository manager (see https://about.gitlab.com).

gitlab.png
 

Polytech/EII has an installed GitLab platform available here : https://gitlab.polytech.umontpellier.fr

gitlab_eii.png

 

You should be able to connect with your Polytech regular login/password.

image_000.png
 
From there, you can to browse existing projects, either yours or other's, that have been made available to the world, or to local users.
 
 

2. Preparing Eclipse (Atollic) and GitLab

Atollic comes with eGit, an integrated Eclipse plugin that can manage Git requests. You may prefer Git command lines... but this tutorial introduces a very simple approach to using GitLab to archive your projets, track changes in source code, and collaborate with other developpers.

In order to have Atollic working with GitLab, one must first setup an authentication mechanism which links your Atollic session to your GitLab account with some degree of security. This is done by means of a SSH-RSA key pair (public/private).

Open Window → Preferences and go to the General → Network Connections → SSH2 category:

image_002.png

SSH2 home is the local folder to store private keys. If you're using your own computer the default path is OK.

When using school computers, you should set the SSH2 home to somewhere in your P:\ folder (e.g. P:\.ssh). Doing so, you will be able to access GitLab from any workstation in the school.

Next, open the Key Management tab. Clic the Generate RSA Key... button.

image_003.png

Then click the Save Private Key... button.

You can ignore the Passphrase, and authorize the .ssh folder creation. Leave the key name as proposed "id_rsa", without any extention.

This will save the private key into your "SSH2 home" local folder (or on your P:\ drive).

image_004.png
 

You can make sure by navigating to this folder :

image_005.png
 
The file "id_rsa" contains your private key. It is a text file you can open with any text editor if you are curious :
 
image_006.png
 
For now, go back to Atollic SSH2 window. Then select the whole public key text, et press CTRL-C to get it into clipboard.
 
image_007.png

 

Now in the Gitlab web interface go to your user Settings:

image_008.png
 
Then select SSH Keys:
 
image_009.png
 
In the Key field, paste the content of the public key you generated with Atollic. Then press the Add Key button.
 
image_010.png
 
 
This will add associate new SSH key with your GitLab account:
 
image_011.png
 
Going back to SSH Keys main window, you should see the newly created key:
 
image_012.png
 
You've created a permanent authentication mechanism between Atollic and your GitLab account that will work for all your projects (present and future). There's no need to do the previous operation again for other projects.
 
 
 

3. Using GitLab to archive and share your Atollic projects

 

3.1. Create a new GitLab project

From GitLab top toolbar, select Projects →Your Projects. Then click the New project button.
 
image_013.png
 
You need to give a name to the project. Although that's not mandatory, let-us give the same name as the Atollic project we want to associate with this repository. You can also add a project description if you like, and finally choose wich level of privacy you want. In any level of privacy, edits are only possible for project members only.
 
When you're done, click the Create project button.
 
image_014.png
 

You’ll end up with an empty new project as shown below. Leave this page open, but put the navigator window aside for the moment.

 

image_015.png
 

 

3.2. Create a local Git repository for Atollic project

 

From the project contextual menu, go to Team→Share Project...

 
image_016.png
 
Then, choose Git and click Next.
 
image_017.png
 

 

The next step is to configure the local Git Repository that will keep track of code history on your computer. Althrough this is not recommended, a simple approach is to have a local repository for each individual project. To achieve this, , just select Use or create repository in parent folder of project, then select the project name, and then click the button Create Repository.

 
image_018.png
 
 
When done, click Finish.
 
 
If you take a look into the project folder, you will notice that a new \.git folder appeared. This is where Git keeps track for your Git actions. There's also a .gitignore file that is new. This file contains a list of directories and files which are not concerned by Git tracking. Basically, you'll find here the \Debug project folder that contains no source code, and is re-generated each time you build the project.
 
image_019.png
 
 
You'll also notice that Project Explorer appearance has somehow changed:
 
image_020.png
 
 
And finally, you’ll see that the contextual Team menu is now populated with a lot of new possible actions:
 
image_021.png
 
 

3.3. First Commit

 

The Commit command is used to save your project changes to the local Git repository.

Launch the Commit action

In the Git Staging panel that opens, select all the Unstaged Changes files (CTRL-A) and drag them into the Staged Changes field. Then enter a Commit Message (mandatory) which describes the purpose of committing.

image_022.png
 
When you're done, click the Commit button .
 

Again, Project Explorer items look different. Actual display tells you that current project files are in sync with the Git repository information (i.e. no file has been modified since last commit).

image_023.png
 
 

3.4. Keep track of code versions

 

Let-us edit main.c and change a little something in the source code. You can for instance modify the delay of the LED ON state.

The initial code:

/*
 * main.c
 *
 *  Created on: 16 août 2018
 *      Author: Laurent
 */

#define DELAY_ON	20000
#define DELAY_OFF	100000

#include "stm32f0xx.h"

int main(void)
{
   ...
}
 
Becomes:
/*
 * main.c
 *
 *  Created on: 16 août 2018
 *      Author: Laurent
 */

#define DELAY_ON	50000    // <-- Longer Delay here
#define DELAY_OFF	100000

#include "stm32f0xx.h"

int main(void)
{
   ...
}

 

Save all and build the project. Make sure the build succeeds...

Project Explorer now shows changes by means of the ‘>’ character applied to the tree structure app/src/main.c :

image_024.png
 
Again, launch the Commit action
 

In the Git Staging panel, you can see that only main.c is now considered for staging. Enter a Commit Message that describes the purpose of committing, and then click the Commit button.

image_025.png
 
 

Open Team Show in History

Select the second commit, and then main.c. You get a detailed view of what has been done:

 

image_026.png
 
 
 

4. Remote Push to GitLab repository

 

Open Team → Show in Repositories View

Then, in the Git Repositories panel, Right-Click Remote and select Create Remote…

image_027.png
 

Give the name you want to the remote server. Select Configure push, and then click OK.

image_028.png
 

In the next window, click the Change button right to the URI text field. You'll end up with the Select a URI window.

Go back to your Gitlab navigator window, open the project you want to use as a remote repository and click the Copy URL to clipboard button under the Clone button.

image_029.png
 
Then paste the content of the clipboard in the URI field of the Location frame. Other fields are automatically populated with the correct information as shown below. When you're done, click Finish.
 
image_030.png
 
In the Configure Push window, then click Save and Push.
 
image_031.png
 
 
You may have questions regarding host authenticity and known host file creation. Answer Yes to both questions.
 
image_032.png
 
image_033.png
 
 
The next window then appears for few seconds, showing Push process progress.
 
image_034.png
 
 
And finally, you'll get the Push Result window. If everything goes well, you'll get this. Just click OK to close.
 
image_035.png
 
You may observe that Git Repositories now dispay the GitLab server as remote repository:
 
image_037.png
 
Then take a look into the GitLab project window. The project is not empty anymore. Instead, it is populated with project files and ready to be shared.
 
image_036.png
 
Click the History button, then select the second commit. You are able to see the edit detail, just like within Atollic. The Push action not only saves the last project state, but also all the Git history:
 
image_038.png
 
 
From now on, you don't have to configure the remote again for this project. You can either:
  • Keep track of your changes locally : Commit
  • Push project onto GitLab for safe archiving and sharing : Commit and Push
 
 

5. Importing from GitLab repository

 
You may also find usefull to use GitLab to import existing projects directly into your workspace.
 
From Atollic, open File → Import...
Select Git→Project from Git, then click Next.
 
image_040.png
 
 
Choose the Clone URI when importing from a remote repository, then click Next.
 
image_041.png
 
 
Now, copy/paste the URL from the GitLab project you want to import, to the URI field of the import window. Other fields are automatically filled. When done click Next.
 
image_042.png
 
 
It takes a little while for Atollic to retreive remote project information. When done, you'll be invited to select the Git project branch to import. For simple projects, it is likely that the only branch available is the master branch. When selected, click Next.
 
image_043.png
 
 
Next, make sure that the destination directory corresponds to your current workspace. Use the Browse button if needed. Then click Next.
 
image_044.png
 
 
At this step, project files have been copied from GitLab into your destination folder, but not yet imported into the Atollic workspace data.
Choose the Import existing Eclipse projects option, then click Next.
 
image_045.png
 
 
Finally click Finish.
 
image_046.png
 
 
The imported project sould appear in the Project Explorer.
 
image_047.png
 
 
You may try a build right away!
If everything goes well, it should build without any additionnal settings:
 
image_048.png
 
 
As you may have noticed, the imported project is still associated with the Git repository (local & remote). You might want to break this association. For this, simply go to Team→Disconnect .
 
You can now use the imported project as you like.