If you want nested repositories without emotional breakdowns in your CI pipeline welcome to this practical git submodule guide for GitLab. This submodule example walks through the real world steps developers and DevOps teams use for repository management and version control so you can stop guessing and start shipping code.

Pick the child repository and a tolerable path

Decide which repository will be the child and pick a folder inside the parent to mount it. The folder name is what your teammates will see in the tree so please use a name humans can tolerate.

git submodule add [repo-url] [path]

That command creates a .gitmodules file and records the exact commit of the child repository that the parent will track. The parent will point at a specific commit in the child so you get predictable builds instead of magic.

Add commit and push so remote is not haunted

Stage the new files and commit the submodule pointer and the .gitmodules file. This keeps everyone on the same page and reduces frantic Slack messages.

git add .gitmodules [path]
git commit -m "Add submodule"
git push

Clone and populate submodules for other users or CI

When someone else clones the parent repo they need to fetch the child repos too. Otherwise they will encounter empty folders and blame you in the project chat.

git clone [repo-url]
git submodule update --init --recursive

You can also use the recursive clone flag in some workflows but update init recursive is the reliable command in scripts and CI jobs.

Move the submodule forward like a responsible adult

When the child repository advances do this from the parent repository root or from within the submodule folder.

cd [path]
# update child to the desired commit or branch
git fetch
git checkout 
# return to parent and commit the pointer change
cd ..
git add [path]
git commit -m "Update submodule pointer"
git push

Remember that the parent records a commit id not a branch name so pushing the child alone does not change what the parent tracks until you update the pointer and push the parent.

Quick tips and small acts of mercy

• Use relative URLs in .gitmodules when parent and child live on the same host. This helps clones and CI runners avoid broken paths.
• For CI include git submodule update --init --recursive in your pipeline steps. This prevents phantom folder drama during builds.
• If you want simpler dependency management consider subtrees or package managers depending on your project needs.

Troubleshooting that saves hours

If a collaborator sees an empty folder check whether they ran git submodule update --init --recursive. If a submodule looks detached check which commit the parent is pointing to and update the child as needed. When permissions cause failures make sure the runner or user can access both repositories on GitLab.

This is a practical git tutorial focused on GitLab workflows for submodule management. Follow the steps here to keep repository management boring and predictable instead of dramatic and expensive.