admin 23 December 2023

1.10. Git and GitLab

Introduction

This tutorial addresses the use of Git and Gitlab together with STM32CubeIDE.

Polytech students must get a clear understanding of the following, because Gitlab will be massively used in the future to evaluate their progress. For others, if not interested, you may just skip this tutorial.

What is Git?

"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

In these tutorials, we will use a single sandbox project my_projet that will grow as you experiment with new STM32 peripherals or new hardware/software mechanisms. Git will be used to take snapshots (current project state) of your progress along the way. Far from a proper Git introduction, here are the few things you need to know.

Together with Git, comes the idea of repositories. A repository is simply a file location where changes in you project files are tracked and recorded. Usually you'll have to deal with 2 repositories:

A local repository. It is located on your computer. The basic operation of recording the changes in your project files to that repository is called a Commit action.
A remote repository. It is located on the network. It is used to share project progress with other developers and therefore allows for collaborative developments. The basic operation of synchronizing the remote repository from the local repository is called a Push action. Remote Git repositories are hosted by servers either on the cloud or on local networks. Well known platforms are GitHub and GitLab. We will use a private GitLab instance, installed on a school server.

A Commit is also the name given to the snapshot resulting from the commit action at a given point in time. In a regular development process, the committing strategy is up to you. You do not need to commit every time you make small changes. You would rather commit when you feel like current project version reached a state that deserve a dedicated archive before you go further. It is a kind of a milestone.

1. GitLab

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

The Polytech GitLab instance is available here : https://gitlab.polytech.umontpellier.fr

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

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

2. Git integration with STM32CubeIDE

On Mac and Linux computers, Git is natively supported. You can therefore perform Git operations, locally or on the remote server, using command line interface (CLI) from any terminal. On Windows, you can install Git for Windows software (https://gitforwindows.org/) to make such things available using the gitbash terminal. Don't do it now unless you're willing to learn Git commands (which would not be a bad idea anyway, but not necessary for now).

In these tutorials, we're not going to use direct commands but an Eclipse Git plugin instead. It provides a simple graphical interface approach to using Git and remote servers to archive your project, track changes in source code, and collaborate with other developers.

At time of writing, STM32CubeIDE does not come with a ready to use Git plugin, but it is pretty easy to install.

Before that, let us check what software and plugins are actually installed. From the main menu, go to Help → About STM32CubeIDE

If the About dialog displays the Eclipse EGit module here, you can probably skip the next steps as EGit is already installed. If you have a fresh STM32CubeIDE install, that should not be the case.

Click Installation Details and review installed packages. In the example below, no external plugins have been installed apart from those included with STM32CubeIDE.

Close Details and the About dialog.

Open Help → Eclipse Marketplace...

In the Marketplaces area, make sure Eclipse Marketplace is selected
In the Find field, enter "egit"
Click the Go button to start searching the Marketplace
When the EGit plugin is found, click Install.

In the next dialog, just leave default selected features and then Confirm >.

Accept the license agreement and Finish.

It will take a little while for the plugin to install. You can monitor the progress in the IDE status bar. You may be asked to trust artifacts along the way.

When done, you'll be asked to restart Eclipse.

After restarting the IDE, go back to Help → About STM32CubeIDE. You should see the Eclipse EGit module now added:

Close Details and the About dialog.

3. Creating a local repository

Now EGit is installed, let us create a local repository and use it for committing project files.

We're going to use the blink3 project for these experimentation. At the moment, it is a clone of my_project, but let us leave the latter apart since it will be the starting point for the "real" thing coming next...

In the Project Explorer, close all projects and open blink3.

Right-click blink3 folder and select Team → Share Project...

First step consists in configuring the local Git Repository, that will keep track of code change history on your computer. Although this is not recommended, a simple choice is to have a local repository for each individual project. For that, just select Use or create repository in parent folder of project, then select the project name, and finally click the Create Repository button.

When done, click Finish.

If you take a look into the project folder, you will notice that a new \.git folder has appeared. It is your local repository. 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. Do not edit the .gitignore file.

You'll also notice that the project appearance in the Project Explorer has somehow changed:

You can get documentation on EGit icon overlays here. For quick reference, the legend below provide a first level of information:

According to the above, project files appear at the moment as '?' untracked.

And finally, you’ll see that the contextual Team menu is now populated with a lot of new possible actions:

The Disconnect command deletes the .git folder (local repository) and completely dissociate the project from any Git history, thus restoring the initial situation. It is useful for instance when you import gited project that you want to disconnect from previous records and associated repositories.

4. First Commit

The Commit action is used to save your project changes to the local Git repository. For a project that was never committed before, well, everything is considered as changes.

From the blink3 contextual menu select Team → Commit...

In the Git Staging panel that opens, the Unstaged Changes area lists all the files that have changed since last commit, i.e. all the source and project files here. All these files should be under Git tracking. All all the files to the Staged Changes area by clicking the button. Alternatively, you can select all of them (CTRL-A) and manually drag them into the Staged Changes field.

At this moment, you may observe that icons in the Project Explorer have changed, now signaling folders as '*' staged and files as '+' added to the tracking process.

Then enter a Commit Message (mandatory) which describes the purpose of committing.

Then, click the Commit button. Again, Project Explorer items look different. Actual display means that current project files and folders are in sync (tracked) with the local Git repository information (i.e. no file has been modified since last commit).

Congratulations, you've successfully performed your fist commit!

You can review commit properties by selecting Team → Show in History

5. Keeping track of code changes

You remember that, since we changed clock settings, the blink3 demo now blinks very fast.

Edit the main() function and apply a ×10 factor on the waiting for loop:

	while(1)
	{
		// LED toggle
		GPIOA->ODR ^= GPIO_ODR_5;

		// Wait
		for(i=0; i<1000000; i++);        // <- Change 100000 to 1000000
	}

Save main.c, build the project and run the application to verify that you obtain the expected effect on the LED blinking (slower blinking).

notice that the change in main.c has been detected and it is now flagged as '>' dirty. That only means that the file main.c is no more in sync with the repository.

main.c is now candidate for staging.

Drag main.c into the Staged Changes area and observe the Project Explorer. Now main.c is flagged as '*' staged.

Provide a Commit Message (e.g. 'Slower blinking') and then click the Commit button.

You can then use the History panel, and select the commit and file your want to review:

6. Remote Push to GitLab repository

Next step is to Push the local repository into a remote repository on GitLab. To do that, we need:

To create SSH key pair (private/public) to authenticate the communication between your computer and GitLab
To register/associate the public part of SSH key with your GitLab account
To create the remote repository via the GitLab web interface
To configure the remote repository within EGit
To perform the Push action

Let's go!

6.1. Creating SSH key pair

In order to have your computer working with GitLab, we must first setup an authentication mechanism which links your computer session to your GitLab account with high level of security. This is done by means of a SSH-RSA key pair (public/private). Note that this authentication method is not specific to STM32CubeIDE.

The first step is to generate a random SSH key pair (public/private) and to store those keys somewhere well identified on your computer. You can use any software tool able to generate SSH keys. On Mac, Linux and Windows, the ssh-keygen command is available from the console. You may also use PUTTYgen if you're after a standalone GUI solution.

Eclipse comes with such a tool, so we'll use that here.

In STM32CubeIDE, open Window → Preferences and go to the General → Network Connections → SSH2 category.

In the General tab, make note of the default SSH2 home path. This is where your keys will be saved and retrieved when necessary.

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 network user folder (e.g. P:\.ssh). Doing so, you will be able to access GitLab from any workstation in the school when logged with your credentials.

Then in the Key Management tab, click the Generate RSA Key... button. This will produce your keys. You can 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 extension. This will save the private key into your SSH2 home local folder (or on your P:\ drive).

You can make sure by navigating to this folder :

The file id_rsa contains your private key. It is a text file you can open with any text editor if you are curious:

The public part id_rsa.pub is also there:

That's the part you need to register and associate to your GitLab account. Just copy (CTRL-A, CTRL-C) the whole file content into the clipboard for now.

6.2. Registering your key within GitLab

Log into GitLab web interface go to your user Settings:

Then from the lateral left toolbar, select SSH Keys:

In the Key field, paste the content of the public key you generated before. Provide a name for the key that helps identifying the location it will authenticate. You also can remove any expiration date so that the key will never expires. Then press the Add Key button.

This will add associate new SSH key with your GitLab account. You should event get an email from GitLab saying so.

Going back to SSH Keys main window, you should see the newly created key:

You don't need to repeat the above steps for every project (key generation and registering). Now that you have a key on your computer, which is registered on your GitLab account, it can be used with any workspace or any project, even beyond STM32 programming and STM32CubeIDE. It is attached to the computer, not a particular software.

6.3. Creating a GitLab remote repository

Still within GitLab web interface, and from the top toolbar, select Projects →Your Projects. Then click the New project button.

Choose Create blank project. You need to provide a name to the project. Although not mandatory, let-us give the same name as the STM32CubeIDE project we want to associate with this repository. You can choose which 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.

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.

6.4. Configure the remote repository within EGit

From GitlLab web interface, copy the project URL in the clipboard using the Copy SSH clone URL button:

From STM32CubeIDE, using the blink3 project menu select Team → Show in Repositories View.

Then right-click on the Remote icon and select Create Remote.

In the next dialog, just keep default Remote name origin and click Create.

In the Configure Push dialog, click the Change... button.

If you correctly copied the URL from GitLab, the Select a URI dialog is automatically filled. Review the fields but do not change anything and click the Finish button. If the fields are not filled, just try again.

In the Configure Push dialog, click the Save button. The new remote repository should now appear in the Git Repositories view:

6.5. Perform the Push action

Everything is now in place for the first Push onto the GitLab server.

There are various ways to achieve this:

One way is simply using the contextual menu Team → Push Branch 'master'...
You can also open the History view, and then from the last commit contextual menu select Push Branch. Let's do that.

You'll get a first dialog that comes only the first time you're using new SSH keys. Click OK.

Same thing here.

In the Push Branch master dialog, simply review the settings and click Preview > button.

And then Push button.

Is takes a short time to process the Push action. You can monitor the progress in the IDE bottom status bar:

When complete, you should get a report. You can just close it, you're done!

Refresh the project page on GitLab, you'll see that the last commit is now there. You can navigate within folder and files and even see the source code.

Actually, not only the last commit is there, but all the commit history. Click on the link:

The whole commit history is there:

Select the Slower blinking link for detailed review. You'll see all the changes this commit holds, just like within STM32CubeIDE:

Before moving to the next section, let us summarize some important concepts:

The pushing action simply synchronizes the remote repository with your local repository.
Because a single commit only holds differences with respect to the previous commit, then when you push your last commit, Git needs all the history of changes since the first commit (i.e. the complete history).
For that reason, it is not possible to push a commit made on project_Y on top of an history built with project_X. Even if project_X and project_Y "look" the same. This happens if you move your project from a computer to another one, or if you change workspaces. You won't be allowed to continue pushing if the history is broken. The only way to migrate a project from a local repository to another one while keeping the link with the remote repository is to follow these steps:
- 1. Make sure before you move that your source project is pushed and in sync with the remote repository
- 2. On the new computer or workspace don't create a new destination project but import the one from the remote repository. Next section covers that topic.
- 3. From there, you may go on developing and committing and keep pushing onto the remote repository.
If for some reason at a given moment you can't push to the remote repository (no internet access, server temporarily unavailable, ...) you can keep going with local commits. Those are not lost. When you'll regain access to the remote server, then pushing the last commit will push everything between that commit and the last one that was already pushed onto the server.

7. Importing a project from GitLab

Because it is impossible for Eclipse to have two identical projects in the same workspace, you need to restart STM32CubeIDE with a fresh folder as workspace. That's only necessary for this section, and you may delete that folder when you're done.

From the main menu, select File → Switch Workspace → Other...

Choose a name for the new temporary workspace (e.g. 'workspace_tuto_import'), then click Launch. This will restart STM32CubeIDE with a fresh workspace.

Then, from the main menu, select File → Import...

In the Import dialog, choose Git→ Projects from Git

Now, using GitLab, copy the project URL you want to import:

Then back to STM32CubeIDE, click Next and choose the Clone URI option:

In the next dialog, paste (CTRL-V) the content of the clipboard and review the source information:

Click Next and EGit starts analyzing the remote repository information looking for branches to import. After a short time, you'll get this:

Click Next, then carefully select your temporary workspace folder as the Destination Directory:

In the next dialogs, just click Next, and then Finish.

When done, the imported project appears in the Project Explorer:

It is not unusual to get some warnings here, because of missing paths, for instance, if project includes absolute paths from the original project. Just try and repair these warnings by reviewing the build settings. There's a warning here because the \bsp folder is missing. It is missing because as it is empty for now, nothing was included into the commits.

Just try to build the project. If you're lucky enough, it builds right-away first time with no errors. Even the debug configuration should be ready to go.

As you may have noticed, the imported project is still associated with the Git repositories:

A new local repository (in the project local folder)
The same remote remote repository as the one you imported from

From there, you have two options depending on what you want to do

If you want to keep on developing that project, then you can go on writing code, then committing then pushing onto the remote.
If you imported that project as a base for another project, then you should disconnect it from the actual repositories using
Team → Disconnect.

IMPORTANT NOTICE FOR POLYTECH STUDENTS

In the following tutorials, every time you pass by a red box as shown below, you have to commit current project state and then push into a dedicated repository on GitLab.

This special remote repository is provided and owned by teacher, but you'll have maintainer rights so you can basically do whatever you want. It is used to monitor your progression. This is part of the evaluation process, and since GitLab info extraction is automated, it is mandatory to use the indicated commit name as a commit message. To avoid typos, simply copy/paste that name (without " " please) into the Commit Message field of the Git Staging panel.

For example, if the box says so:

Commit name "This is an example"
-

Push onto Gitlab

Commit the project using Commit name as Commit Message as shown here:

Be careful if your navigator translates the web site in a non-English language. Translated commit names will be discarded in the evaluation process... You've been warned.

For the very first commit (coming shortly), you'll have to configure the remote repository as explained in the above tutorial, using URI obtained from the remote repository. Then, you'll be able to execute first push. This will create the master branch onto GitLab repository.

You only need to configure the remote repository once. We'll use the same project all along the tutorials. For second commit and further, you may simply use the Commit & Push... button each time you pass by the red box.

Last advices:

Keep all commits in the master branch (i.e. do not create other branches).
Check your commits both in STM32CubeIDE and in GitLab after the push action, especially the first ones, to make sure everything works as it should.

The tutorials program includes 44 commits. By the end of the training, your project history should display something similar to this:

Take a breath, and let's go!