How We Tried Using Git Submodules (And Why It Did Not Work for Us)

Jul 13

By Lukas Varkalis, Engineering Manager at Kilo Health

You might know that feeling when you are talking with your colleague and discussing a technical problem in your project, and he says that everything is working fine on their computer. Not the greatest feeling, right? 

I hope you try to understand why it is happening instead of pushing the changes to the server and testing it there.

Those issues could appear for various reasons. It can be different node or browser versions, or you just have not pulled the latest changes. Because it could also be possible. 

Today, I would like to share some experiences and lessons that we learned working with Git submodules. But before that, a short introduction about what it is and how they work generally.

What are Git submodules?

Submodules are Git repositories nested inside a parent repository’s working directory. Simply put, it allows you to include repositories as sub-folders inside another repository. SHA-1 hash will link them to know which version of the package you are using now. 

This approach with submodules could help you keep everything in one place and easily maintain shareable packages.

The nice thing about submodules is that Git allows you to commit and push to these repositories independently. It helps when you use merge requests, issues, and different versions to develop a library for several projects.

Everything sounds good from the first look: you could maintain packages more easily and don’t have to stick to a specific version. So we decided to use this approach with a few of our internal packages and check how it goes.

First, we tried to implement it with a small team in one of our projects. A submodule you can add very easily just by running one command:

git submodule add<user>/<repository-name> /path/to/directory

Then using NPM workspaces, you can install dependencies required by the added package. After that, some additional configuration for ESLint, and Typescript, and this is it. You’re ready to go! ?

3 issues with Git submodules

Everything worked perfectly for a small developers team, where you always have clear and effective communication. But after working with more teams and less experienced developers, we realized that there are some cons to working with Git submodules. 

I will share three of them from our experience:

1. The learning curve

Running a project locally using Git submodules is not intuitive for new developers. 

They have to know some additional steps to take. For example, download submodules from remote directories and install their dependencies. It could be hard to understand for backend developers.

git submodule update —init && npm install

Also, not all developers are familiar with this implementation. So, you have to write clear documentation and guidance on how to work with submodules: fetch the latest version, check out to a new branch, create a new release, and so on. It takes time and effort to do it, especially for junior developers.

2. Hard to track the version in use

Reviewing pull requests of other developers could be very annoying. You can’t see which library version they are using or switching on. You could see only the SHA-1 hash, which is hardly readable and says nothing about a specific version. 

For example:

Subproject commit 33d6a12560f348c5c663c004ac13c7a124dd982c

3. Manual updates

Changes in the recorded SHA-1 hash are not automatically reflected in the submodules. 

This means that if someone updates the recorded version of a submodule and you pull their latest changes in the parent repository, your submodule repository will still be pointing to the old version of the submodule. 

You have to run the command manually to update it:

git submodule update

The same problem is when you solve merge conflicts at the parent repository: it still doesn’t update the submodule pointer. You also have to do it manually.

To sum up

After some discussions and unpleasant incidents, we decided to use NPM packages, the previous solution, instead of Git submodules. It is more straightforward, everyone is familiar with it, and there is no learning curve.

Also, we look forward to trying new and different approaches to improve our developers’ experience with shareable libraries. So stay tuned!

Would you like to join this journey? Check out the open positions here.

Lukas Varkalis
ex Front-End Guild Lead
A tech guy who is passionate about building high-performing engineering teams and always cares about people. Lukas has launched over 50 MVP projects and can easily build one over the weekend. Loves to study design, data, and human behavior.

Latest articles

Matas Olendra: Innovators Aren’t Magicians, It’s All About Principles
Mar 15
Kilo Heroes

I’m Matas, and when asked, I refer to myself as an intern — always learning. However, research, strategy, business development, and idea generation are the cornerstones of my work. I want to pull back the curtain and give you an…

Read more
Deimante Butke and her 3 roles: Full-Time Job, Pursuing a PhD, and Motherhood
Feb 15
Kilo Heroes

I’m Deimante, currently Head of Marketing at Kilo Health, and a big lover of this company. My journey to being hired at Kilo has been quite the ride.  How it all started? I underwent interviews with 11 different people and…

Read more
Kilo Health Launches an Incubator Challenge: Ready to Test Yourself in a Startup?
Jan 12

Ever dreamt of taking the lead, even if the path isn’t crystal clear? Or to have someone believe in you and offer you a chance to figure out whether you would thrive in a startup environment? Speaking of which, Kilo…

Read more
Kilo Health Celebrates Its 10th Anniversary: Milestones and Lessons
Oct 25

A whole decade has raced by in the blink of an eye for us at Kilo Health, and what better way to celebrate than to reflect on the milestones and lessons over the years? Do you know where we started?…

Read more
Vitalijus Majorovas: Co-Founders Also Need Balance
Aug 23
Kilo Heroes

We, the co-founders, are just ordinary individuals with grand ambitions. There are times when we work twice as long and intensely as others, yet we’re equipped with the same amount of daytime, energy, and capacity. However, as leaders in the…

Read more
Following Your Gut: How to Avoid the Startup Graveyard
Aug 11
Kilo Heroes

There’s no enchanting tale behind how I became a part of Kilo Health. In truth, some of us regular folks simply have regular journeys, and that’s perfectly fine. What counts is that today, I hold a successful product in my…

Read more
Kilo Health Breaks Records: 84% Growth, 213M Euros in a Year
Aug 8

Reflecting on your achievements from the previous year is advantageous. That’s exactly what we did, proudly demonstrating our boundless aspirations through an impressive 84% growth and 213 million euros. So let’s put our hands in the air and celebrate together,…

Read more
I Don’t Need a New Job: Or How to Join Kilo Health Within 10 Minutes
Jul 14
Kilo Heroes

I joined Kilo Health back in 2019, and I can prove that when people’s values and mindsets align, great things can be accomplished, even if you don’t have a plan. BoomeranGO!, the first and only product for children provided by…

Read more
4 Ways Startups Can Draw Inspiration From Hollywood 
Jun 14
Kilo Heroes

Lighting, sound, set, and actors are essential components of a film studio, but they are not the sole factors that define its success.  Consistent creativity, appreciation of talent, and adaptability to market trends are a few of the things that…

Read more
Internal Career: Why It Benefits Both Employees and Employers?
Apr 5

Internal career development opportunities are increasingly recognized as one of the most valuable benefits for employees. In fact, 62% of Learning and Development (L&D) professionals state that they are prioritizing internal mobility in 2024. Moreover, according to data from LinkedIn, individuals who…

Read more
Why Startups Stumble: Revealing the Key Reasons for Failure
Mar 7

When you initially envision creating a groundbreaking startup, the idea of failure might not immediately cross your mind. However, it can appear later, potentially haunting you until the very launch. Entrepreneurs must keep in mind that failure is an integral…

Read more

Stay on top of health and wellness news

Kilo Outsider is a curated monthly newsletter for everyone who cares about health – from investors to policy makers, from entrepreneurs to healthy living enthusiasts.