News Stay informed about the latest enterprise technology news and product updates.

How to create Git submodules in GitHub and GitLab

In a previous git submodules tutorial I added submodules to a stand-alone repository. There was no push or pull to or from GitHub or GitLab. In this GitLab and GitHub submodules add example I will pull from two independent GitHub repositories and then create the submodule linkage between them. The video at the end of this tutorial demonstrates the same git submodule add in GitLab. The two repositories will be named:

  • surface
  • submarines

The git submodule add command create a .gitmodules file.

I will allow you to deduce on your own which one is the parent module and which on is the Git submodule.

How to create submodules in GitHub

The following list of steps will add Git submodule GitHub relationships between two repositories:

  1. Clone the parent or top-level repository
  2. In the root of the parent issue a git submodule add command and provide the GitHub repository’s URL
  3. Issue a git status command to verify a .gitmodules file is created in the parent project
  4. Add the .gitmodules file to the index and perform a git commit
  5. Push the GitHub submodule add commit back to the server

GitHub submodule add commands

The following is the list of command performed in the GitHub submodule add example.

submodule@example:~$ git clone
submodule@example:~$ git log --oneline
submodule@example:~$ git cd surface
submodule@example:~$ git submodule add
submodule@example:~$ git status
submodule@example:~$ git git add .
submodule@example:~$ git git commit -m "Add GitHub submodule"

GitHub submodule push

It should be noted that the created GitHub submodules are treated as separate, independent repositories. To prove this point, a file named tugboat.html is added to the surface module and a file named xia.html is added to the added GitHub submodule. Note that a push from each repository is required to move changed files back to the GitHub server. A push from the parent does not automatically force new commits in the submodule to be pushed as well.

submodule@example:~$ git touch tugboat.html
submodule@example:~$ git add .
submodule@example:~$ git commit -m "Add the tugboat file"
submodule@example:~$ git push origin
submodule@example:~$ cd submarines
submodule@example:~$ touch xia.html
submodule@example:~$ git add .
submodule@example:~$ git commit -m "Add xia class sub"
submodule@example:~$ git push origin

Create submodules in GitLab

If you want to learn how to create submodules in GitLab instead of GitHub, the following GitLab tutorial walks you through it:

The subsequent tutorials will show you how to clone Git submodules and how to delete Git submodules. Please follow along.








Start the conversation

Send me notifications when other members comment.

Please create a username to comment.