my-notes

git_submodules

1 min read

git submodules

Include other repositories within your repository.

➕ Adding Submodules

Add a Submodule

git submodule add https://github.com/user/repo.git

Adds repository as submodule in current directory.

Add to Specific Path

git submodule add https://github.com/user/repo.git libs/repo-name

Adds submodule at specified path.

Add Specific Branch

git submodule add -b develop https://github.com/user/repo.git

Adds submodule tracking the develop branch.

📊 Submodule Structure

graph TD
    A[Main Repository] --> B[.gitmodules file]
    A --> C[submodule folder/]
    C --> D[Separate Git repo]
    B --> E[Contains URL and path mappings]

📥 Cloning with Submodules

Clone with All Submodules

git clone --recurse-submodules https://github.com/user/repo.git

Clones repository and all submodules in one command.

Initialize After Clone

git submodule init

Initializes submodule configuration.

Update Submodules After Clone

git submodule update

Fetches submodule content at recorded commit.

Init and Update Together

git submodule update --init

Initializes and updates all submodules.

Include Nested Submodules

git submodule update --init --recursive

Initializes and updates submodules including nested ones.

🔄 Updating Submodules

Update to Latest Commit

git submodule update --remote

Updates submodule to latest commit on tracked branch.

Update Specific Submodule

git submodule update --remote submodule-name

Updates only the specified submodule.

Pull Within Submodule

cd submodule-folder
git pull origin main
cd ..
git add submodule-folder
git commit -m "Update submodule to latest"

Manual way to update submodule.

📋 View Submodule Status

List Submodules

git submodule status

Shows current commit of each submodule.

Detailed Status

git submodule status --recursive

Shows status including nested submodules.

View .gitmodules

cat .gitmodules

Shows submodule configuration file.

🗑️ Removing Submodules

Step 1: Deinitialize

git submodule deinit submodule-name

Removes submodule from working tree.

Step 2: Remove from Git

git rm submodule-name

Removes submodule folder and .gitmodules entry.

Step 3: Clean Cache (Optional)

rm -rf .git/modules/submodule-name

Removes cached submodule data.

Commit the Removal

git commit -m "Remove submodule"

Commits the submodule removal.

⚙️ Configuration

Set Submodule Branch

git config -f .gitmodules submodule.name.branch develop

Sets which branch the submodule should track.

Shallow Submodules

git config -f .gitmodules submodule.name.shallow true

Makes submodule clone shallow (less disk space).

🔄 Common Workflow

After Pulling Main Repo

git submodule update --init --recursive

Ensures submodules are at correct commits after pull.

Configure Auto-update

git config --global submodule.recurse true

Automatically updates submodules on git pull.

💡 Tips

Foreach Command
git submodule foreach 'git pull origin main'

Runs command in each submodule.

Submodule Commits

After updating submodule, you must commit the change to main repo.

🔗 Related

#git #submodule #advanced

Built with mdgarden