Terminologies

• Parent repository (the repository that will hold the reference to submodule)
• Remote parent (the remote repository of the parent repository)
• Local parent (the local clone of the parent repository)
• Submodule repository (the actual repository of submodule)

Key Players

• our local repository containing submodule
• remote local repository containing submodule
• submodule's repository
• colleagues local repository containing submodule

Initial state without submodule

If you havent added submodule to your parent repository, you will have the following state.

Adding submodule to local repository

You can add the git submodule to your local parent repository as follows:

git clone git@github.com:bishtbytes/git-mainproject-repo.git git-mainproject-repo
cd git-mainproject-repo

git submodule add git@github.com:bishtbytes/git-submodule-repo.git git-submodule-repo
git submodule init
git submodule update

Pushing submodule from local to remote

Once you have the submodule added to your local repository, you can push this change to remote parent repository as follows:

git add git-submodule-repo .gitmodules
git commit -m "Added submodule repository"
git push

Initial state with local uninitialized

You could already have a remote parent with submodule in it, but havent pulled the remote to your local yet.

To clone remote parent to local

You can clone remote parent to local as follows:

git submodule update --init --remote

After new commits on the submodule

Over time your submodule will get the commits and look different than when you added it to parent repository.

Pull commit on local parent

To get the new changes of submodule to your local repository, you have to pull the changes as follows:

cd <submodule-path>
git pull origin <branch-name>
cd ..
git add <submodule-path>
git commit -m "Update submodule"
git push origin <branch-name>

Push commit to remote parent

Once you have the new commits pulled into your local repository, you can push the same to remote repository as follows:

git push origin <branch-name>

Teammate can pull this change

At this point, your local and remote are also updated with new commits in the submodule. You can ask your team mates to pull the changes too using the following commands:

git pull origin <branch-name>
git submodule update --init --remote