Git Submodule v.s Subtree
Overview
Incorporating libraries that are separately version controlled but requiring it as a dependency can be done in git but there are different ways of doing it. As an example I have used Git’s submodule and subtree.
I started with a public repository which is a BASH script for creating VPN tunnels. This is publicly available on my Github page. I then wanted to use the script in another project which just so happened to be set to private although this would apply if I was creating a public repository as well. I then wanted to add another repository so I had 2 references which submodule doesn’t allow.
All of this can be worked out if you were using something like Gradle or Maven but this about platforms that may not have their own dependency management system.
Submodule
A submodule is where a separate repository code is cloned into a sub directory of another repository. It will keep all commits separate and avoids keeping 2 copies of the source code in different repositories. At the same time you can perform a fetch / pull on the sub directory to get the latest version of the code. Git will retain the information of where to fetch from once it’s setup.
To add a submodule to your repository, go to the parent directory for where you want the other repository to reside and:
git submodule add git@github.com:dannytsang/bashTunnel.git
where the URL is the repository URL. This will also add an entry into .gitmodule file which keeps track of submodules. All of this will need to be committed as a change set for others to pick up.
If you need to remove it at any point edit the file and remove the remove and delete the sub directory.
To update the submodule with any changes made in it’s repository run the command:
git submodule update --remote
Subtree
Subtree is fairly similar to submodule in that you are bring in another repository as a sub folder to your git repository. The biggest difference are the commands and the ability to have multiple subtrees in a project as suppose to 1 submodule.
Using the same example above, to add another repository as a subtree you need to run the command:
git subtree add --prefix [directory] [repository URL] [banch] [remove history]
For example:
git subtree add --prefix src/lib git@github.com:dannytsang/bashTunnel.git master --squash
To update the subtree replace the add command with pull:
git subtree pull --prefix src/lib git@github.com:dannytsang/bashTunnel.git master --squash
Summary
Both methods require the code to be “merged” into your branch because it is treated as a separate from your code. Once the merge is committed and pushed up all other users of the repository will be forced to take in the updated submodule or subtree.
Submodule is slightly easier because the commands are similar and a lot shorter to subtree but some aliasing / scripting should help with that.
Alternatives To Git Submodule: Git Subtree
7.11 Git Tools – Submodules
