Have you ever wanted to have a git repository included inside another git repository?
And the did
git tell you something like this?
hint: You've added another git repository inside your current repository. hint: Clones of the outer repository will not contain the contents of hint: the embedded repository and will not know how to obtain it.
I guess you’re unlucky then! (pardon me! I am sarcastic sometimes 😊)
But don’t worry! As strange as it sounds that
git disallows having a git repository inside a git repository, but the git team did this knowingly – because they wanted to make sure, no duplicated code gets tracked and similar stuff.
That’s why, they named it…
And it is exactly as it sounds like.
A git repository inside a git repository.
By using git submodules you will have the following setup:
- a main git’s repository
- a submodules’ git repository
Adding a submodule
cd yourself into a main repository’s root and add a submodule just like so:
git submodule add <repository-url> Cloning into '<repository-name>'… remote: Counting objects: 11, done. remote: Compressing objects: 100% (10/10), done. remote: Total 11 (delta 0), reused 11 (delta 0) Unpacking objects: 100% (11/11), done. Checking connectivity… done.
You have just added “a git repository inside your git repository” – bravo! 🥳 Or in other words, you have just created a git submodule.
git status to see, what have just happened:
$ git status On branch master Your branch is up-to-date with 'origin/master'. Changes to be committed: (use "git reset HEAD …" to unstage) new file: .gitmodules new file: <repository-name>
There are two changes:
- a new file “.gitsubmodules”
- a new directory <repository-name>
In your main repository, there will be a new file called
It will contain just a name of the submodule and it’s repository url, for example something like this
[submodule "random-string"] path = random-string url = email@example.com:hanakivan/random-string.git [submodule "array-range"] path = array-range url = firstname.lastname@example.org:hanakivan/array-range.git [submodule "array-range-es6"] path = array-range-es6 url = email@example.com:hanakivan/array-range-es6.git
A submodule directory
It is a directory of your submodule that you have jut checked out. You can go work in it, commit your changes and simply push it.
Then go to the main repository, go for
git status and you will see the following:
-Subproject commit 4a4f15217e59899cb7f04cdbd1cab8e1b1045e12 +Subproject commit 556d41b5389984a1dbeecd94a161e3df53597666
This you need to commit as well – and this will be committed insides the main repository so as it can keep track of the latest commits of the submodules
Remove a submodule
Should be pretty straightfoward:
cd <main-repository-filder> git rm <submodule-name>
After this git will remove the submodule’s dir from the main repository root and will also modify
.gitmodules file by removing the reference link for the submodule’s repository.
The decision is up to you, you can start using git submodules, but you can go for a totally different approach, like using a npm or packagist for your packages and avoiding submodules at all.
They have pretty vast documentation and certainly you can accomplish a lot with it, but if you need to do some advanced stuff, I would argue to avoid using this completely (I’d rather have duplicated commits than deal with this kind of stuff 😂) – but hey, if complexity is not an issue for you – as the famous saying goes De gustibus non est disputandum.
Stay up to date.
Yours in coding,