Submodules

Submodules allow you to reuse components across projects, such as plugins or libraries, and to control access to areas in your project. To overcome the trickiness of Git submodules, Anchorpoint applies certain standard procedures, such as not allowing you to commit when you are on a detached head.

How Git submodules work and why they are "tricky"

In development, submodules are often used to get a Git repository for a module (e.g., an open source networking module) into your application. Once you import that repository as a submodule, you are importing it at a particular state, meaning a particular checked-out commit. Let's say it's checked out at the commit "releasing v1.45." This means that if other contributors make changes to the open source network module, these changes are not automatically applied to your project. That is the intended behavior, because you want to control when you update that submodule to the latest state to avoid, for example, breaking changes.

Now, your main repository, which contains your game project, needs to know that this submodule will always stay on v1.45, especially when other team members are working on your game. To do that, your main repository will have a commit that includes a so-called "submodule reference." This looks like a changed file in your commit, but it's just a pointer that references commit "releasing v1.45" in your networking submodule. If you now want to update your networking submodule to the latest state, you can do that with a simple Git pull in your submodule. Now, your main repository will see that something in your submodule has changed. Right now, this pull that you did in your submodule is only happening locally and is not shared with your team members. In your main repository, you will see a change that looks like a file, but is basically referring to your submodule. That is because your main repository was referring to the submodule at a different state, so a different commit. If you think that nothing broke your project, you can then tell your main repository that this should be the default state for your submodule now by committing that change. Now, your main repo will point to the latest version of your submodule. If your team members pull your commit in the main repository, the submodule will be updated on their end.