DEV Community πŸ‘©β€πŸ’»πŸ‘¨β€πŸ’»

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

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 https://github.com/mirumee/saleor-platform.git --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)

SUBMODULES
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.

Example:
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 https://github.com/<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 (5)

Collapse
aidookingsley profile image
aidookingsley

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.

Grateful.

Collapse
daryl profile image
daryl-sen

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

Collapse
jjokah profile image
John Johnson Author

You're welcome. Thanks for taking the time to do so. πŸ™

Collapse
tawanda profile image
Tawanda Minya

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

Collapse
jjokah profile image
John Johnson Author

Thank you too.

🌚 Turn on dark mode

πŸ”  Change your default font

πŸ“š Adjust your experience level to see more relevant content

Β 

Head to your account's Settings to do all this and more.