Want to nest one repo inside another and pretend everything is tidy while actually juggling two histories Well welcome to the glamorous world of git submodules This guide walks through adding a submodule to a GitHub repository and keeping the pointer tidy so your team does not cry

Prepare your main repo and pick a subproject

Make sure your working tree is clean and decide which repository will live inside the main repo and where it will sit in the file tree The main repo will only store a pointer to a specific commit in the subproject so history stays separate and manageable

Checklist before you start

• Commit or stash local changes in the main repo
• Choose the subproject repo URL as REPO_URL and a path like libs/subproj for PATH

Add the submodule

Run the add command which creates a .gitmodules file and a pointer in the main tree

git submodule add REPO_URL PATH

That creates a .gitmodules entry and places a gitlink in PATH which points to a commit in the subproject

Commit the submodule reference and push

Stage the new files and push the pointer to origin so other clones know about the submodule

git add .gitmodules PATH
git commit -m "Add submodule"
git push

Clone or update with submodules on another machine

When someone clones your repo they need to fetch submodule data as well The quickest safe sequence is

git clone REPO_URL
git submodule update --init --recursive

If the repo is already cloned and you pulled new commits with submodule changes run

git submodule update --init --recursive

Work inside the submodule and update the pointer

The submodule is a separate git repo inside your working tree If you need to change what commit is referenced enter the submodule do your fetch or checkout then update the main repo pointer

cd PATH
git fetch
git checkout BRANCH_OR_COMMIT
cd ..
git add PATH
git commit -m "Update submodule"
git push

Note that by default submodules can end up in a detached HEAD state If you want the submodule to track a branch use the set branch command or update .gitmodules

git submodule set-branch --branch BRANCH PATH

Remove a submodule when it outlives its usefulness

Removal needs a few steps to clean up the .gitmodules entry and repo metadata

git config -f .gitmodules --remove-section submodule.PATH
git rm --cached PATH
rm -rf .git/modules/PATH
git commit -m "Remove submodule"
git push

Common gotchas and tips

• Submodules store a commit pointer not a branch so remember to update the parent repo after changing the submodule commit
• Track a branch inside the submodule to avoid surprise detached HEADs with git submodule set-branch or by adding branch = BRANCH to .gitmodules
• Use --recursive when initializing or updating to avoid missing nested submodules
• If CI or scripts need reproducible builds prefer pinning commits instead of floating branches

There you go You added a submodule you committed the pointer you taught the team how to clone and update and you learned how to remove it without leaving ghost metadata behind Your main repo stays slim while the subproject keeps its history neat and separate That is the whole point and sadly the only neat thing about git sometimes