Git Submodules Guide

This document provides instructions for working with Git submodules in the KINTSUGI project.

Current Submodules

Submodule	Path	Purpose
Skills_Registry	`Skills_Registry/`	The maintainer’s registry of learnings from earlier development sessions (optional for building or using KINTSUGI)

Quick Start

Cloning the Repository with Submodules

When cloning KINTSUGI for the first time, use one of these methods:

# Option 1: Clone with submodules in one command (recommended)
git clone --recurse-submodules https://github.com/smith6jt-cop/KINTSUGI.git

# Option 2: Clone then initialize submodules
git clone https://github.com/smith6jt-cop/KINTSUGI.git
cd KINTSUGI
git submodule update --init --recursive

Pulling Updates with Submodules

Always include submodules when pulling:

git pull --recurse-submodules

Common Operations

Check Submodule Status

# View current submodule state
git submodule status

# For nested submodules (if any)
git submodule status --recursive

Update Submodules to Tracked Commits

If teammates have updated submodule pointers:

# Sync submodules to commits tracked by parent repo
git submodule update

Update Submodules to Latest Remote

To get the latest changes from submodule remotes:

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

# Update a specific submodule
git submodule update --remote Skills_Registry

Making Changes in a Submodule

Navigate to the submodule directory:
```
cd Skills_Registry
```
Checkout the appropriate branch:
```
git checkout main
```

Make your changes and commit:

git add .
git commit -m "feat: your changes"
git push

Return to parent and commit the updated pointer:

cd ..
git add Skills_Registry
git commit -m "chore: update Skills_Registry submodule"
git push

Recommended Git Aliases

Add these aliases to simplify submodule operations:

# Clone repositories with all submodules
git config --global alias.clone-all 'clone --recurse-submodules'

# Pull with automatic submodule updates
git config --global alias.pull-all 'pull --recurse-submodules'

# Update all submodules to tracked commits
git config --global alias.subup 'submodule update --init --recursive'

# Update all submodules to latest remote
git config --global alias.sublatest 'submodule update --remote --merge'

Usage:

git clone-all <repository-url>
git pull-all
git subup
git sublatest

Troubleshooting

Detached HEAD in Submodule

If git status shows (modified content) for a submodule:

git submodule update

Submodule Directory is Empty

git submodule update --init --recursive

Submodule Changes Not Reflected

After pulling, always run:

git submodule update

Reset Submodule to Tracked Commit

If a submodule has unwanted local changes:

cd Skills_Registry
git checkout .
git clean -fd
cd ..
git submodule update

Adding a New Submodule

# Basic addition
git submodule add <repository-url> <path>

# With specific branch tracking
git submodule add -b main <repository-url> <path>

# Commit the addition
git add .gitmodules <path>
git commit -m "chore: add <name> submodule"

Removing a Submodule

# Remove submodule entry from .gitmodules
git config -f .gitmodules --remove-section submodule.<path>

# Remove submodule entry from .git/config
git config --remove-section submodule.<path>

# Remove submodule from index
git rm --cached <path>

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

# Commit the removal
git commit -m "chore: remove <name> submodule"

Best Practices

Always use --recurse-submodules when cloning or pulling to ensure submodules stay in sync.
Don’t commit build artifacts in submodules - they’re system-specific and should be built locally.
Update after teammate changes - Run git submodule update after pulling when others have modified submodule pointers.
Commit submodule pointer changes - After updating a submodule, commit the updated reference in the parent repository.

Use branch tracking for actively developed submodules:

git config -f .gitmodules submodule.Skills_Registry.branch main

Keep submodules shallow if history isn’t needed:
```
git submodule update --init --depth 1
```