Handle Git Submodules with ease

Handle Git Submodules with ease

Using VS Code and TortoiseGit

It helps me when things are visualized. Reading lengthy articles or documentation might be boring. Lots of commands for terminal and technical terms might be overwhelming. I even prefer articles to videos sometimes when they are written clearly with the help of images.

In this article I explain what Git submodules are with some visual help. Also I describe how can we use them with 2 tools. The first one is TortoiseGit and the 2nd one is Visual Studio Code.

What is a Git submodule?

Submodules are repositories inside other Git repositories. As an example, let’s assume we have 2 repositories called ‘skeleton’ and ‘core’.

Linking submodule via .gitmodules configuration fileLinking submodule via .gitmodules configuration file

Above you can see that skeleton contains .gitmodules file. We have to make sure that this configuration file is created and initialized. We can use the following commands for that:

git submodule add -b master [URL to Git repo] 
git submodule init


In this file we have to define:

  • path to submodule folder

  • url to submodule repository

  • branch

It could look like this:

[submodule “app/styles/core”]
path = app/styles/core
url = ../../repo/core.git
branch = master

I am not good at remembering commands and at the beginning I wasn’t sure what commands to run in order to make submodule work. The thing is submodules are not automatically updated when you update your main repository. For example you pull the changes in skeleton, and then you have to update the submodule separately.

I use 2 tools that help me with Git so I don’t have to type the commands. If you prefer just terminal that’s great. Hats off to you :-)

VS Code

I use Visual Studio Code for writing code and updating the repositories. Switch to Source Control panel (CTRL + SHIHT + G) in your project and you will see the repositories. In our example, we can see skeleton (main repository) and also core submodule. We defined .gitmodules before so VS Code recognizes that.

Since submodule is just another repository which points to a certain commit, you can click on the synchronization icon next to branches (master) and the repositories are updated. You can also quickly check out another branch just by clicking on the name of the branch.

You just don’t have to type:

git submodule update

But, if you track branches in your submodules and you need to update another branch that hasn’t been checked out before, the following command could be useful:

**git submodule update --remote --merge**

TortoiseGit for Windows

In fact, if you use TortoiseGit (similar programs might support it too if you are not on Windows or use something else), there’s no need to type even those 2 commands I mentioned before. In the explorer, right click on the project and you will see the options for adding and updating the submodule.


This is all we need to cover some basic work with submodules without typing or remembering many commands (we can’t avoid them all together). Submodules can be tricky at times and you might need to merge, diff or perform other actions that are out of the scope of this article. I wanted to show you that with the help of some tools they aren’t that scary.

Visual Code Studio and TortoiseGit can help us a lot to manage them. Give them a try.

Thank you!