Sync

Usage

/sync [subcommand] [scope]

Subcommands

Scope

• all (default) — All 26 submodules
• work — Work repositories only
• personal — Personal repositories only
• <repo-name> — Single specific repository

Execution Protocol

CRITICAL: This skill exists because git sync is the #1 activity (68+ sessions) and the #1 source of friction. Follow this protocol exactly.

Phase 1: Discovery (read .gitmodules, NOT .gitignore)

WORKSPACE_ROOT="/d/workspace-hub"
cd "$WORKSPACE_ROOT"

# Get submodule list from .gitmodules (NEVER parse .gitignore)
git submodule status

Phase 2: Pre-flight checks

For each submodule:

1. Check if HEAD is detached → fix to tracking branch
2. Check for uncommitted changes → stash before pull
3. Check for divergence: git rev-list --count HEAD..origin/main and git rev-list --count origin/main..HEAD

# Per-repo status check
cd "$WORKSPACE_ROOT/$repo"
git fetch origin --quiet


*See sub-skills for full details.*
### Phase 3: Pull (with stash safety)

```bash
cd "$WORKSPACE_ROOT/$repo"

# Stash if dirty
if ! git diff --quiet HEAD 2>/dev/null; then
    git stash push -m "pre-sync-$(date +%Y%m%d-%H%M%S)"
    STASHED=true
fi

# Pull with rebase (never merge for sync pulls)

*See sub-skills for full details.*
### Phase 4: Commit dirty repos

```bash
cd "$WORKSPACE_ROOT/$repo"
if ! git diff --quiet HEAD 2>/dev/null; then
    git add -A
    git commit -m "chore: sync updates

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>"
fi

Phase 5: Push

cd "$WORKSPACE_ROOT/$repo"
AHEAD=$(git rev-list --count origin/main..HEAD 2>/dev/null || echo 0)
if [ "$AHEAD" -gt 0 ]; then
    git push origin main
fi

Phase 6: Update workspace-hub submodule pointers

cd "$WORKSPACE_ROOT"
git add $(git submodule status | awk '{print $2}')
if ! git diff --cached --quiet; then
    git commit -m "chore: sync submodule pointers

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>"
    git push origin main
fi

Phase 7: Verification (MANDATORY — never skip)

cd "$WORKSPACE_ROOT"
git submodule status

Success criteria (ALL must pass before reporting success):

• No submodules in detached HEAD state
• No submodules with uncommitted changes
• No submodules with unpushed commits
• Workspace-hub submodule pointers match remote HEAD

See sub-skills for full details.

Existing Script

The ./scripts/repository_sync script handles the mechanics:

# Quick status of all repos
./scripts/repository_sync status all

# Pull all
./scripts/repository_sync pull all

# Full sync (commit + push)
./scripts/repository_sync sync all -m "End of day sync"

Use the script where it works. Fall back to manual git commands per-repo when the script doesn't cover a case (detached HEAD fix, stash conflict resolution, submodule pointer updates).

Windows / MINGW64 Notes

• Path root is /d/workspace-hub/ (not D:\)
• while [ "$(pwd)" != / ] loops never terminate — use $WORKSPACE_ROOT var
• mklink /J for junctions requires unquoted paths
• Shell scripts must use LF endings (CRLF breaks bash)
• Enable long paths: git config --global core.longpaths true

Anti-Patterns (NEVER do these)

• NEVER parse .gitignore to discover repos — use .gitmodules
• NEVER report sync as successful without verification phase
• NEVER auto-resolve stash pop conflicts or merge conflicts
• NEVER force-push without explicit user confirmation
• NEVER skip repos silently — report every repo's status
• NEVER use git add -A without first running git status

Iron Law

No sync shall be reported as successful without completing Phase 7 verification and confirming all four success criteria pass — ever.

Rationalization Defense

Red Flags

These phrases signal you are about to violate the Iron Law:

• "sync looks good" (without running git submodule status)
• "all repos pulled successfully, we're done"
• "skipping verification to save time"
• "probably fine — no errors were reported"

Sub-Skills

• Error Handling