Notes on git submodules.
Most of the
What is it? #
Git submodules allow you to keep a git repository as a subdirectory of another git repository. Git submodules are simply a reference to another repository at a particular snapshot in time. Git submodules enable a Git repository to incorporate and track version history of external code.
– Source: Atlassian: Git submodules
Note that the main repository and the submodule are effectively separate repositories. Committing the main repository does not directly commit the changes in the submodule. Similarly, remote changes to the submodule do not get pulled along with a pull of the main repository.
Adding a submodule #
Navigate to the main repository, then run:
git submodule add <url to the repo on github> <path for where to put submodule>
This action clones the repository.
The <path for where to put submodule> is optional. Without it, the default path is the current directory. Handy to use if you want to specify where to place the submodule or if you want to give the submodule a specific name.
At this point,there should be a .gitmodules file at the top level. This is how git tracks the submodules. The .gitmodules file contains specifications of the path and url, along with an identifier for the submodule.
Adding a specific branch of the submodule #
git submodule add -b <submodule branch name> <submodule repo url>
Initialize submodule configuration file #
If the submodule configuration doesn’t already exist, run:
git submodule init
Check status of submodule #
Check the overall repository:
git status
Results should include some mention of elements related to the submodule.
For example:
modified: <submodule> (new commits)
This won’t include the details of what got changed in the submodule, only that there is now a submodule present.
Pull submodules #
Git commands will ignore the submodule unless you issue commands specific to the submodule.
To explicitly pull the submodules, run:
git pull --recurse-submodules
Optionally, update the git config so it automatically recurses through submodules.
git config submodule.recurse true
Alternatively, navigate to the nested submodule directory, which effectively changes the working git repository, and pull as usual.
git pull # from within the submodule directoery
Cloning repository and its submodules #
If this is the initial clone of a repository that contains submodules, run:
git clone --recursive <main repo URL>
If the primary repository has already been cloned, but not the submodules yet, run:
git submodule update --init
If there are nested submodules:
git submodule update --init --recursive
Clone multiple submodules #
Clone multiple submodules (up to 8):
git submodule update --init --recursive --jobs <number of submodules>
git clone --recursive --jobs <number of submodules> <git url>
--jobs can be shortened to just -j
Update the submodule #
git submodule update
Execute command on each submoldule #
Any arbitrary git command can be run on all the submodules. For instance, to reset, run:
git submodule foreach --recursive 'git reset --hard'
Delete submodule from repository #
A submodule can be deleted with the following sequence:
git submodule deinit -f -- <submodule name>
rm -rf .git/modules/<submodule name>
git rm -f <submodule name>
Deploying site on Netlify with submodules #
It’s possible to set up a Blogdown site to deploy on Netlify with a submodule that might contain a specific group of content.
A bit of a gotcha: deploying a site to Netlify using submodules requires that .git/config and .gitmodulesutilize the Github https repo path, not the ssh path.
After some trial and error, I found that this only works if the submodule is public.
Reference: https://answers.netlify.com/t/hugo-site-deployment-failed-due-to-host-key-verification/783