How to create Git submodules in GitHub and GitLab by example

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 creates a .gitmodules file.

I will allow you to deduce on your own which one is the parent module and which one 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 commands performed in the GitHub submodule add example.

submodule@example:~$ git clone https://github.com/cameronmcnz/surface.git
submodule@example:~$ git log --oneline
submodule@example:~$ git cd surface
submodule@example:~$ git submodule add https://github.com/cameronmcnz/submarines.git
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 Git/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

Check out this Git and GitLab tutorial for beginners to learn more.