Using Git submodules

Clone submodules during deployment allows you to use submodules in your Git repository. They’re usually listed in a .gitmodules file at the root of your Git repository. When you push via Git, tries to clone them automatically.

Here is an example of a .gitmodules file:

[submodule "app/Oro"]
	path = src/Oro
	url =
[submodule "src/OroPackages/src/Oro/Bundle/EntitySerializedFieldsBundle"]
	path = src/OroPackages/src/Oro/Bundle/EntitySerializedFieldsBundle
	url =
[submodule "src/OroB2B"]
	path = src/OroB2B
	url =

When you run git push, you can see the output of the log:

Validating submodules.
  Updated submodule git:// 4 references updated.
  Updated submodule git:// 229 references updated.
  Updated submodule git:// 11 references updated.

Error when validating submodules 

If you see the following error:

Validating submodules.
  Found unresolvable links, updating submodules.

E: Error validating submodules in tree:
    - /src/Oro: Exception: commit 03567c6 not found.

   This might be due to the following errors fetching submodules:
    - HangupException: The remote server unexpectedly closed the connection.

Since the Git server can’t connect to GitHub via SSH without being granted an SSH key to do so, you shouldn’t use an SSH URL:, but you should use an HTTPS URL instead:

Use private Git repositories 

When using Git submodules that are private repositories, URLs with the HTTPS protocol fail with errors such as the following:

GitProtocolError: unexpected http resp 401 for

To fix this, follow these steps:

  1. Change your module declarations to use SSH for URLs.

    Your existing declaration might look like this:

    [submodule "support/module"]
        path = support/module
        url =

    Change this to the following:

    [submodule "support/module"]
        path = support/module
        url =
  2. Add the project’s public key to your remote Git repository. This allows your project to pull the repository from the remote Git service.

Removing submodules 

These steps aren’t specific to, but kept as a reference for Git so that submodules are effectively removed before entering the build process.

  1. Delete information for the submodule you’d like to remove from .gitmodules.

  2. Stage changes to .gitmodules:

    $ git add .gitmodules
  3. Remove the submodule configuration from .git/config.

  4. Remove the submodule from the repository (without trailing slash):

    $ git rm --cached path_to_submodule
  5. Remove the submodule files in .git from the repository (without trailing slash):

    $ rm -rf .git/modules/path_to_submodule
  6. Commit the changes:

    $ git commit -m "Removed submodule."
  7. Remove the submodule code locally, now no longer tracked:

    $ rm -rf path_to_submodule