DEV Community

Cover image for SUBMODULES: A git repo inside a git repo.
John Johnson Okah
John Johnson Okah

Posted on

SUBMODULES: A git repo inside a git repo.

As I followed the installation guide to set up saleor-platform on my system, I just copied and pasted all the series of commands required, into my terminal without even understanding what most of them meant.

The first command was

git clone --recursive --jobs 3
Enter fullscreen mode Exit fullscreen mode

I quite understood git clone <repo-url>, but had no idea what recursive --jobs 3 was doing there.
Though, It didn't really bother me as long as I don't get any error.

But later as I browsed through the repository on github, and clicked on a folder, it was as if I was redirected to another repo. 😲
Immediately I went to consult Google and asked him: "Can you have a git repository in a git repository?".
And, voila! I found submodules.

This is a summary of what Submodules is:
(from this blog)

It often happens that while working on one project, you need to use another project from within it. Perhaps it’s a library that a third party developed or that you’re developing separately and using in multiple parent projects. A common issue arises in these scenarios: you want to be able to treat the two projects as separate yet still be able to use one from within the other.

Git addresses this issue using submodules. Submodules allow you to keep a Git repository as a subdirectory of another Git repository. This lets you clone another repository into your project and keep your commits separate.

Let’s say you’re working on a project called Slingshot. You’ve got code for y-shaped stick and a rubber-band.

Alt Text

At the same time, in another repository, you’ve got another project called Rock—it’s just a generic rock library, but you think it’d be perfect for Slingshot.

You can add rock as a submodule of slingshot. In the slingshot repository:

git submodule add<user>/rock rock
Enter fullscreen mode Exit fullscreen mode

At this point, you’ll have a rock folder inside slingshot, but if you were to peek inside that folder, depending on your version of Git, you might see … nothing.

Newer versions of Git will do this automatically, but older versions will require you to explicitly tell Git to download the contents of rock:

git submodule update --init --recursive
Enter fullscreen mode Exit fullscreen mode

If everything looks good, you can commit this change and you’ll have a rock folder in the slingshot repository with all the content from the rock repository.

On GitHub, the rock folder icon will have a little indicator showing that it is a submodule:

Alt Text

And clicking on the rock folder will take you over to the rock repository.

That’s it! You’ve embedded the rock repository inside the slingshot repository. You can interact with all the content from rock as if it were a folder inside slingshot (because it is).

On the command-line, Git commands issued from slingshot (or any of the other folders, rubber-band and y-shaped-stick) will operate on the “parent repository”, slingshot, but commands you issue from the rock folder will operate on just the rock repository:

cd ~/projects/slingshot
git log # log shows commits from Project Slingshot
cd ~/projects/slingshot/rubber-band
git log # still commits from Project Slingshot
cd ~/projects/slingshot/rock
git log # commits from Rock
Enter fullscreen mode Exit fullscreen mode

Joining a project using submodules:
Now, say you’re a new collaborator joining Project Slingshot. You’d start by running git clone to download the contents of the slingshot repository. At this point, if you were to peek inside the rock folder, you’d see … nothing.

Again, Git expects us to explicitly ask it to download the submodule’s content. You can use git submodule update --init --recursive here as well, but if you’re cloning slingshot for the first time, you can use a modified clone command to ensure you download everything, including any submodules:

git clone --recursive <project url>
Enter fullscreen mode Exit fullscreen mode

Submodules allow you to include or embed one or more repositories as a sub-folder inside another repository.

At the end, I was like how come nobody told me about this.

Alt Text

Top comments (6)

aidookingsley profile image

Thank you John Johson. I chanced on your article in my quest for Git repo in git repo and your article has given me clear understanding.
The good thing is, I'm writing from the future which is 2022, and so I want to add the latest update which works in git.

git submodule add nodule

= the repo you're working from's url
nodule = beomes the name of the new repo intended to be inside your repo.

This will come off as useful to any newbie like me who comes accross this article.


daryl profile image

I created an account just to say thank you! A lot of guides have these convoluted explanations and I just couldn't absorb them for some reason. I read yours, even though it's a little outdated now, and finally got submodules set up and running

jjokah profile image
John Johnson Okah

You're welcome. Thanks for taking the time to do so. 🙏

wendykkelly profile image
Wendy Kelly

Thank you! So clear. Do you feel that adding an e-commerce site (specifically next/commerce) to my current nextjs site is an appropriate usecase for submodules?
I have not yet come across this exact usecase and would love your input. Thank you!

tawanda profile image
Tawanda Minya

Thank you, I also just opened an account to say thanks!

jjokah profile image
John Johnson Okah

Thank you too.