HowTo - Git Submodule.md

HowTo - Git Submodule

REF.: Git Submodules basic explanation
REF.: Git submodules best practices

Note:

• The submodule is (just) a separate repository.
• Don't forget to commit changes!

---

Adding a submodule

# Links the submodule with folder "dir_name";
# if you don't set a dirname the repo's name will be used instead
git submodule add https://path-to/the-submoule-repo.git [dir_name] 
git commit -m "Add submodule <name>"

Updating the submodule's code (or resetting to detached HEAD)

git submodule update [--init] [--recursive]

Cloning a repository with submodules

git clone --recursive [email protected]:name/repo.git

Useful configuration settings

# Add status of submodules to `git status`
git config --global status.submoduleSummary true

# W/o config setting 
git diff --submodule=log
# See submodule changes with `git diff`
git config --global diff.submodule log

# Check if already set to "on-demand"
git config --global fetch.recurseSubmodules 

Updating a submodule

# Change into the submodule folder and git switch to the submodule's repository
cd dir_name
git fetch
git log  # verify what you have
# Checkout on the desired checksum
git checkout -q <ckecksum>
# or use 'git pull' to get latest submodule changes
# or merge main into the detached branch using
cd ..  # go back to your repo
# Note: do NOT use `git submodule update`
git add <submodule>  # commit changes

Removing a submodule

# Remove permanently 
git rm dir_name 
# This will update the `.gitmodules` file as well 

# Unregister but keep reference in `. gitmodules` file 
git submodule deinit
# Remove remaining empty local submodule folder (w/o using `git`) 
rm dir_name