Shell Integration : Cloning

I’ll go ahead and assume that you’re a serious programmer. Someone who works for a living or at the very least someone who doesn’t want people to look at their work and roll their eyes judgmentally. That means you’ve got some version control to take care of now. Only Python programmers who use Arduinos unironically think Git is an insult.

If you haven’t installed Git on your PC yet, you can download it from the official site . The installer will ask you to make a lot of choices that may not be clear to you. It is safe to use the default choices.


STM Shell is distributed as a Git repository published on GitHub. You’re going to:

  • Initialize your project for Git and perform an initial commit
  • Clone STM Shell into your project
  • Set it up as a Git submodule

Thus, your project’s development history will be kept separate from that of STM Shell. This will let you pull new versions when I release any, without creating confusion as to who modified what.

Let’s get to it.

To the best of my knowledge there isn’t a menu option in CubeIDE to let you initialize your project as a Git repo. Thankfully, that’s very easy.

Right-click on your project in the “Project Explorer” pane and, under “Show In”, select “System Explorer”. This will open your operating system’s file explorer to where your project is stored :

Get into your project’s folder. I’m expecting you installed Git with context menu integration, so that you’ll get the “Git Bash Here” option.

This will open a Bash terminal window, in which you can enter the git init command. That’s it, your project is now under version control.

Keep this terminal open though, you’re going to need it a few more times.

Note that EGit (the Git plug-in for Eclipse) isn’t smart enough to immediately detect what you just did. In CubeIDE, you’ll need to close your project and re-open it for the IDE to become aware that is now under version control. Here’s a before-and-after photo :

Now CubeIDE displays your project’s repository and the active branch. The “>” mark indicates that the project contains modifications that haven’t been committed yet. Quite logical since we’ve yet to make an initial commit… which we’ll do right away, this time from CubeIDE.

Right-click on your project again and go into the Team submenu, where you’ll find the Commit command.

This will open the Git Staging pane :

Type-in a thoughtful, inspiring commit message such as “a small step for a man, a great step for humanity” or “initial commit”, stage all the changes (using the double-plus-sign icon) and hit the “Commit” button. That’s it.

Now get back to your Git Bash terminal to clone STM Shell using :

git clone

The output should show no error. If it does, you’re in for some Googling because there could be a lot of reasons your cloning command failed. One thing’s for certain, it’s not my fault. It’s most likely GitHub’s.

Back in CubeIDE, your project should now look like this :

You’ve now got nested repositories. But if you look at the Git Staging pane, you’ll find that the “STM_Shell” folder and its contents are not detected as modifications. This is normal. Git is efficient enough that it won’t let you track modifications that are already being tracked. So you’ll just see this :

That “?” icon is there because you still need your project repo to track that it is using the STM Shell repo, and which commit. That is what declaring it as a submodule is for.

Return to your Bash terminal and use the following command :

git submodule add ./STM_Shell

This command will also automatically stage a commit for both the submodule folder and the Git “.gitmodules” file :

Give it a memorable message like “this is the day Nefastor bestowed a shell upon my humble project” or “added STM Shell submodule”, and then commit.

Henceforth, should you pull future versions of my library into your project, Git will only tell you that this submodule has changed. You will still be able to checkout any commit of that library that works for your project. Nifty.

And with that, we’re all out of Git wizardry… at least for a few minutes.

There’s one more thing to take care of : at this point, CubeIDE doesn’t consider the “STM_Shell” folder to be part of your project’s code. It will not be compiled when you build your project. That would be vexing. But it’s easy to fix. Start by expanding the “STM_Shell” folder in the Project Explorer :

Following convention, the “Src” subfolder contains the library’s source files and the “Inc” subfolder contains the include files.

Select the “STM_Shell” folder and hit ALT+ENTER to open its properties. Navigate the dialog box to “C/C++ Build”. You’ll see that “Exclude resource from build” is ticked. In the “Configuration” drop-list, select “All configuration”, untick, then hit “Apply and Close”.

Next, right-click the “Inc” subfolder and select “Add/remove include paths…”

Tick all configurations (they should be ticked by default) and click OK.

If you’ve done everything right so far, you should now be able to build your project with no error and no warning. If you do get any, then you need to review your work. I might make it look easy but this is still a fairly complex process with a lot of steps and commands you don’t use every day. It’s easy to miss something. What, did you think I wrote this website for you ? I wrote it for myself, because I’m pretty sure I’ll forget half of this by the next time I need to deploy my shell.

Anyway, it’s time to code a little.