Git Submodules: Managing Nested Repositories

# Main repository
my-project/
├── .git/
├── src/
├── package.json
└── lib/              # Submodule (separate repository)
    ├── .git/
    ├── utils.js
    └── README.md

# 1. Include external libraries
- Open-source dependencies
- Shared component libraries
- Third-party tools

# 2. Monorepo management
- Separate deployable units
- Independent versioning
- Team autonomy

# 3. Project dependencies
- Specific versions of libraries
- Forked repositories
- Internal shared code

# Add a submodule
git submodule add https://github.com/user/repo.git lib/repo

# This creates:
# 1. .gitmodules file
# 2. lib/repo directory with cloned repository
# 3. staged changes in parent repository

# Add to specific branch
git submodule add -b develop https://github.com/user/repo.git lib/repo

# Add with specific name
git submodule add --name my-repo https://github.com/user/repo.git lib/repo

[submodule "lib/repo"]
	path = lib/repo
	url = https://github.com/user/repo.git
	branch = develop

# Clone repository with submodules
git clone --recurse-submodules https://github.com/user/project.git

# Or clone and init submodules
git clone https://github.com/user/project.git
cd project
git submodule init
git submodule update

# Initialize and update all submodules
git submodule update --init --recursive

# Update submodules to latest commits
git submodule update --remote

# Show submodule status
git submodule status

# Output explanation:
# + 1234567 (1.2.0) lib/repo  # + = modified
# - 1234567 (1.2.0) lib/repo  # - = not initialized
#  1234567 (1.2.0) lib/repo  # regular = clean

# List all submodules
git submodule foreach 'echo $name'

# Update submodule to remote branch tip
cd lib/repo
git pull origin main
cd ../..
git add lib/repo
git commit -m "Update submodule"

# Update all submodules
git submodule update --remote

# Update specific submodule
git submodule update --remote lib/repo

# Merge updates in submodule
cd lib/repo
git checkout main
git pull origin main

# Navigate to submodule
cd lib/repo

# Make changes
echo "new feature" > feature.txt

# Commit in submodule
git add feature.txt
git commit -m "Add feature"

# Push submodule changes
git push origin main

# Update parent repository
cd ../..
git add lib/repo
git commit -m "Update submodule to latest"

# Submodules are in detached HEAD by default
cd lib/repo
git status
# HEAD detached at 1234567

# To work on submodule:
git checkout main  # or your branch
# Now you can commit changes

# Or work directly in detached mode
git checkout -b feature-branch

# Configure submodule to track branch
git config -f .gitmodules submodule.lib/repo.branch main
git add .gitmodules
git commit -m "Track main branch in submodule"

# Update all submodules to their tracking branches
git submodule update --remote --merge

# Sync submodule URLs from .gitmodules
git submodule sync

# After changing remote URL in .gitmodules
git submodule sync --recursive

# Update submodules after sync
git submodule update --init --recursive

# Add submodule
git submodule add <url> <path>

# Initialize submodules
git submodule init

# Update submodules
git submodule update

# Clone with submodules
git clone --recurse-submodules <url>

# Remove submodule
git submodule deinit <path>
git rm <path>
rm -rf .git/modules/<path>

# Fetch all submodule changes
git submodule foreach git fetch origin

# Run command in all submodules
git submodule foreach 'git status'

# Pull all submodules
git submodule foreach 'git pull origin main'

# Clean all submodules
git submodule foreach 'git clean -fdx'

# Show submodule logs
git submodule foreach 'git log -1'

# Problem: Submodule shows detached HEAD
cd lib/repo
git status
# HEAD detached at 1234567

# Solution 1: Checkout branch
git checkout main

# Solution 2: Create branch from commit
git checkout -b feature-branch

# Solution 3: Reattach to branch
git checkout main
git merge 1234567

# Problem: Submodule directory empty
ls lib/repo
# (empty)

# Solution: Initialize and update
git submodule init
git submodule update

# Or in one command
git submodule update --init

# Properly remove a submodule
# 1. Deinitialize
git submodule deinit -f lib/repo

# 2. Remove from git
git rm -f lib/repo

# 3. Remove .git/modules directory
rm -rf .git/modules/lib/repo

# 4. Remove .gitmodules entry
git config -f .gitmodules --remove-section submodule.lib/repo
git add .gitmodules

# Always commit submodule updates
cd lib/repo
git pull origin main
cd ../..
git add lib/repo
git commit -m "Update submodule to latest main"

# Configure submodule to track branch
git config -f .gitmodules submodule.lib/repo.branch main

# Always checkout branch in submodule
git submodule foreach 'git checkout main'

# README.md

## Submodules

This project uses the following submodules:

- `lib/repo`: Utility library (main branch)
- `lib/shared`: Shared components (develop branch)

To update submodules:

# Makefile or package.json scripts
"scripts": {
  "postinstall": "git submodule update --init --recursive"
}

# Or use npm hooks
npm install husky
# .husky/post-install
git submodule update --init --recursive

# Submodules
✓ Separate version control
✓ Independent releases
✓ Clear boundaries
✗ Complex workflow
✗ Detached HEAD confusion

# Git Subtree
✓ Simpler workflow
✓ Single repository
✗ Larger repository size
✗ Merge conflicts

# Monorepo
✓ Simple workflow
✓ Shared history
✗ All-or-nothing commits
✗ Slower operations

# Add subtree instead of submodule
git subtree add --prefix=lib/repo https://github.com/user/repo.git main

# Update subtree
git subtree pull --prefix=lib/repo https://github.com/user/repo.git main

# Push changes back to subtree project
git subtree push --prefix=lib/repo https://github.com/user/repo.git main

name: CI

on: [push, pull_request]

steps:
  - uses: actions/checkout@v3
    with:
      submodules: recursive
      token: ${{ secrets.GITHUB_TOKEN }}  # For private submodules

  - name: Install dependencies
    run: npm install

  - name: Run tests
    run: npm test

variables:
  GIT_SUBMODULE_STRATEGY: recursive

test:
  script:
    - npm install
    - npm test