updated 6 months ago
4 min read
The most widely used version control framework is Git. Git keeps track of the modifications you make to files so you can see what you've done and go back to previous versions if you need to. Git also facilitates teamwork by allowing different people's modifications to be combined into a single source.
The git module is an alias used in the codebase of your project to describe all of the git sub modules on which your project relies.
What is a git submodule?
If you're working on a project within a git repository and you're overly reliant on another project within another git repository, you can either copy files from one repository and insert them into the other, or you can use package managers like npm, ruby Gem or PyPi.The trouble with having code from a package manager is that it's challenging to configure, and if you're copying, it's much more difficult to combine the copied files with the improvements made to the code base by its authors.
Simply a git submodule enables you to hold a git repository in the subdirectory of another git repository and handle their commits independently. Submodules aren't aware of git branches and aren't changed directly when the host repository is updated.
When is it appropriate to use git submodules?
Do the git submodule suit well with your use case? Let's figure it out below.
- If the project's code you choose to use in your project don't change all that much.
- When a project is rapidly evolving and modifications can interrupt APIs, submodules may be used to keep the project at a certain version.
How to add submodule to your git project?
In my case, I've set up a git project over here you can clone it and follow along to practice what we are going to be talking about.
git clone https://github.com/codekinHQ/git-submodule-blog/tree/main
I have another project over here that i would like to add it as a submodule into my project, I run
git submodule add https://github.com/makuzaverite/codekin.tech.git Cloning into '/home/user/path/blog-examples/git-submodule-blog/codekin.tech'... remote: Enumerating objects: 220, done. remote: Counting objects: 100% (220/220), done. remote: Compressing objects: 100% (144/144), done. remote: Total 1217 (delta 143), reused 116 (delta 73), pack-reused 997 Receiving objects: 100% (1217/1217), 1.26 MiB | 313.00 KiB/s, done. Resolving deltas: 100% (719/719), done.
Now have codekin.tech project as a submodule inside our project. It went on and cloned the repository we have targeted it pull, where you do
dir commands inside your project you are going to see a file named
.gitmodules what is that? it's content in my case is
[submodule "codekin.tech"] path = codekin.tech url = https://github.com/makuzaverite/codekin.tech.git
.gitmodules is a configuration file that holds the urls of your project's submodules as well as their local names.
How do I clone a project that contains git submodules?
when you do
git clone project_url in project submodule by default you shall find not folder with no files in them. to get files back you need to run two commands
git submodule init # initialize your local configuration git submodule update # Fetches file from the submodules at their specific commits in your configurations
Another way to do this is to use the
--recurse-submodules flag when copying the repository. This wil auto matically initialize and submodule and update each submodule..
git clone --recurse-submodules #project url here
How to update your submodule
You may want to update your submodules to their latest version from their origin, run
git submodule update
When you have changed remotes in submodules run
git submodule update --remote
How to get changes from submodules' remote?
You can easy get changes from submodules upstream but running two commands
git fetch git merge
This easier way to do this is by running a single commands
git submodule update --remote #submodule_name
If you want to execute a command in each of your submodules, foreach is a great tool to have.
# logs git status in each submodule git submodule foreach 'git status'
You can use aliases for commands which might become long and you can set options configuration for them
git config alias.sdiff '!'"git status && git submodule foreach 'git status'" git config alias.spush 'push --recurse-submodules=on-demand' git config alias.supdate 'submodule update --remote --merge'
I think this helped you to understand git submodules this is the time to move from sub directories to Submodules