Git Submodule Tutorial
Introduction
In our Git projects, sometimes we will include and use other Git projects as submodules. One easy and reproducible way to do this is simply to clone the other Git projects and copy the Git projects in the directories under our own projects. However, it is also likely that the project we are working on has close relationships or collaboration with the submodule Git projects, and we want the submodules to be always up-to-date. In this way, we will use git submodule functions to manage submodules.
In this short blog post, I will talk about the basic protocols of using git submodule correctly in our projects in practice. For more comprehensive usages, please go to the reference section.
Tutorial
Create Submodules in Our Own Git Projects
We will use git submodule add to create submodules in our own Git projects.
1 | $ git submodule add [-b <branch>] [-f|--force] [--name <name>] [--reference <repository>] [--depth <depth>] [--] <repository> [<path>] |
For example, if we want to use TensorFlow project branch r1.14 as our submodule in directory third_party/tensorflow. In our Git project git-submodule-demo, we run the following commands.
1 | $ cd git-submodule-demo/ |
We then check what submodule information has been added.
1 | $ ls -a |
We then push the changes to GitLab or GitHub.
1 | $ git add . |
On GitLab or GitHub, there will be symbolic links to the Git projects for the submodules.
Remove Submodules in Our Own Git Projects
It used to be very tricky to remove the Git submodules. However, the latest protocol for the new versions of Git makes life easier. To remove the TensorFlow submodule we just added.
1 | $ git submodule deinit -f third_party/tensorflow/ |
We then check if the submodules have been totally removed.
1 | $ ls -a |
Once the submodules were removed, we could add the exact same submodules.
1 | $ git submodule add -b r1.14 https://github.com/tensorflow/tensorflow.git third_party/tensorflow |
If the submodules were not removed cleanly and there is residual information left, there will be problems to add the exact same submodules.
Work with Submodules in Other Git Projects
Sometimes we would have to work on Git projects from others which contain submodules. After git clone, we actually would not have the submodules cloned.
1 | $ cd git-submodule-demo/ |
To retrieve the submodules, we have to run the following command.
1 | # Git submodule would use the submodule information in the `.gitmodules` to retrieve the submodules. |
Sometimes we want to create submodules that are exactly used in other Git projects for our own projects. We just have to check the submodule information in the .gitmodules file, and used the method we described in “Create Submodules in Our Own Git Projects” to create those submodules accordingly.
Update Git Submodule When Necessary
Sometimes, the submodules from the third parties might have been updated, and we would also like to update the submodule in our project accordingly. We could go to the submodule directory. We checkout to the branch that we want to update via git checkout if necessary. Then we do git pull to pull the new updates to the submodule.
Alternatively, if we would like to update all the submodules without considering too much, just run the following command.
1 | $ git submodule update --remote --merge |
Finally, we push the changes to GitLab or GitHub via git add, git commit, and git push.
Final Remarks
We have to be careful when we use git submodule because the submodules might be updated without sending notifications to you and all your dependencies might break.
References
Git Submodule Tutorial