In setting up the stad.us blog and website, I had the opportunity to start using the
git submodule command for the first time to work with submodules. I don’t pretend that there are other ways to use submodules, but these are the commands I use the most.
Anything can be added as a submodule to an existing git project as long as the submodule is itself a git project. In my case, I forked the Beautiful Hugo theme for this Hugo based website. It needs to be linked from the themes directory in my site repository.
To add the theme to my website repository, I use the
git submodule command (here I use the actual Beautiful Hugo repository instead of my custom theme):
mkdir themes cd themes git submodule add https://github.com/halogenica/beautifulhugo.git beautifulhugo
Note that you will have a new
.gitmodules file that you will want to add to your parent repository.
Using the submodule command in the above example will automatically clone the repository and pull content so you are ready to go after this command. If you clone your parent repository, you will need to execute these commands to fetch your submodules:
git submodule init git submodule update
You can also use the
--recurse-submodules argument in your original clone:
git clone --recurse-submodules <url>
If you make changes to the code within the submodule, you can commit those changes just like any other change. They are tracked within the submodule and not within the parent module. Also see the
git submodule update command to pull changes that others have made to the submodule and have committed to the repository.
To remove a submodule, use the
git rm command:
git rm (submodule)
This will change the
.gitmodules file so you will need to commit that change.
Look at the submodule command.