Skip to main content

Submodules

Submodules enable you to reuse components, such as plugins or libraries, across projects and control access to different areas of your project. To help you overcome the complexities of Git submodules, Anchorpoint applies certain standard procedures, such as preventing you from committing when you are on a detached head.

A beginner's guide to how Git submodules work in general

The concept of submodules​

Each submodule is its own Git repository inside another Git repository. The submodule stays linked to its root repository, and you control which version of it your project uses. The submodule is always at a particular version in your project. For example: You are building a Unity plugin in a Git repository. Now, you import this plugin as a submodule in your root repository. Let's say you have it in two projects. One project uses Unity 6.0 and the other one Unity 6.3. In your plugin repository, you can have both versions. The root repository of each project will link to either a commit (or even a branch) for Unity 6.0 or Unity 6.3. So you can import the plugin with different versions.

Submodule links are connections in your root repository that appear as file changes in Git. They point to a particular commit, and therefore a particular version, of the submodule. For example, there is a submodule link for our plugin for Unity 6.0 and for Unity 6.3.

In Anchorpoint, submodule links can have different states, similar to files.

  • Modified: This means that the submodule has changed files that have not yet been committed.
  • Checked out at a different commit: This means that the submodule has committed changes, but they are not yet registered in the root repository. If a team member pulls the root repository, the submodule will be checked out at an older state that has already been registered in the root repository.
  • Added, deleted, conflicting: The same status that applies to files.

Submodules in Anchorpoint​

This video provides an overview on how submodules are handled within Anchorpoint. It covers connecting to submodules, committing from submodules as well as checking out submodules at different states.

Anchorpoint features for frictionless submodule usage​

Anchorpoint adds convenience and security mechanisms around submodules to avoid troubleshooting sessions with non-technical users, such as:

  • Protecting from committing on a detached HEAD
  • Protecting from pushing updates in the root repository without pushing the submodule first. This can lead to pull errors for other team members.
  • Reminding the team member to also update the root repository when submodule changes have been pushed.
  • Reattaching the branch after checkout
  • File locking across submodules

Adding a submodule​

Submodules must be added via the Git command line. This step should be done by your technical lead. Team members will simply consume and automatically connect to the added submodules in your repository if they have the proper Git credentials.

To add a submodule use the following git command:

git submodule add PATHTOYOURREPOSITORY RELATIVEPATHTOYOURFOLDERINYOURPROJECT

For example:

git submodule add https://github.com/org-name/library.git external/library

Joining a project with a submodule​

When joining a project or cloning a commit that includes a new submodule link, Anchorpoint will automatically check out the submodule if the credentials are correct. You can also disconnect the submodule in the submodule menu by right-clicking on a submodule if you want to save disk space.

If you want to join a project and check out the submodules manually, you have to uncheck "Connect Submodules" in the advanced settings when joining a project.

File locking in submodules​

Changing files in a submodule will also trigger automatic file locking. Pushing these files will release the file lock just like in the root repository.

Reverting submodules​

Reverting a submodule link in the root repository will also revert all changed files in that submodule. If the submodule link that gets reverted points to a commit in the submodule, the submodule will be checked out to its previous state that has been committed in the root repository.

When pulling changes in the root repository that have a submodule link, the submodule will be automatically checked out at that commit.

Handling the detached head​

Once a submodule is checked out (e.g., on pulling or on initial clone), the submodule commit that is checked out is not attached to a branch automatically. This state in Git is called a "detached head" state. Anchorpoint detects that state and prevents committing files during that state. Before committing, you will be asked to pick a branch.

Pushing submodule changes​

You will push submodule changes the same way you push in a normal Git repository. To register the new commit in the root repository, you have to update the submodule link. Once the push is completed, Anchorpoint will show an "Update Root" button that will navigate to the Timeline so that you can also commit and push the submodule link.

Local only submodule commits

If you have a local submodule commit that has not been pushed to the Git server, Anchorpoint will inform you to push the submodule commit first, before pushing the submodule link in the root repository. If you push a submodule link without pushing the commit of the submodule, the next person would not be able to pull the root repository.

Conflict handling​

In case you have a local committed submodule link and you are pulling a commit that contains the same link but points to another commit in the submodule, you need to resolve a conflict. Anchorpoint will ask you to pick which version of the submodule pointer should be the latest. Once you have resolved the conflict, make sure to go to the submodule and sync the changes there. Then, you might create a new version of the submodule link in the root repository that needs to be committed as well.

Using submodules with the Unity or Unreal plugin​

This feature is not currently fully supported. The plugin only detects changes in the main repository, not in the submodules. However, file locks are displayed in submodules. You cannot commit via the plugin; you always have to commit via the Anchorpoint desktop application.