I’m in the process of seeing if using Git Submodules can help simplify my workflow when it comes to building freemium WordPress plugins. This serves as a small cheat sheet to help me remember some important submodule specific commands.
Clone a repository with nested submodules
Clone a repository and automatically include all submodules using
You will not need to run
init because that’s done automatically.
git clone PATH-TO-REPO --recursive
Get all submodules after cloning
Checkout all submodules if you didn’t while cloning main repository. This will run through and include all nested submodules as well.
git submodule update --init --recursive
Adding a new submodule
Adding a new submodule to an existing repository is straight forward.
git submodule add REMOTE-GIT-URL my-local-path/submodule-name
Moving a submodule to another path.
You’ll need to use the submodule command to correctly move the submodule to another path. Otherwise git will not be able to track the submodule.
git submodule mv old-path/my-submodule new-path/my-submodule
Removing a submodule
Removing a submodule is not as easy as just removing the folder. You’ll need to run the following command to ensure submodule is completely cleaned up from the repository.
git submodule rm path/my-submodule
Updating a submodule to a later commit.
I recommend reading https://chrisjean.com/git-submodules-adding-using-removing-and-updating/
Basically a submodule is a ‘shortcut’ to the original repository, which means that you can just
cd into submodule and
checkout any branch. You can also modify the submodule and push commits directly up to main repository. This is the main selling point for me!
Explanation of Submodules
I’ve also come across this great post explaining submodules. https://gist.github.com/gitaarik/8735255
Github doesn’t include submodules inside the release archives or the main ‘download’ repository. It’s annoying and have been requested for years. You’ll have to upload custom builds of your project as a zip or whatever file you need.