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 --recursive
You will not need to run update or 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

Limitations

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.