Skip to main content

Git Workflow Automation Guide

Automated git workflows for CODITECT repositories with submodule synchronization.

Quick Start​

# Full repository sync (recommended)
/git-sync --target all --mode full

# Preview changes first
/git-sync --target all --dry-run

# Analysis only (no commits)
/git-sync --mode analyze

Git Sync Command​

Basic Usage​

/git-sync [options]

Options​

OptionDescriptionDefault
--targetSync target: all, submodules, masterall
--modeMode: full, analyze, commit-onlyfull
--dry-runPreview without making changesfalse
--forceSkip confirmation promptsfalse

Examples​

# Full sync of everything
/git-sync --target all --mode full

# Only sync submodules
/git-sync --target submodules --mode full

# Analyze without committing
/git-sync --mode analyze

# Force sync (no prompts)
/git-sync --target all --force

Bottom-Up Sync Workflow​

The sync follows a bottom-up approach to ensure proper git history:

1. Analyze all repositories
         ↓
2. Commit changes in each submodule
         ↓
3. Push submodule changes
         ↓
4. Update submodule pointers in master
         ↓
5. Commit and push master
         ↓
6. Verify all changes

Why Bottom-Up?​

  1. Submodules must be committed first - Master repo references specific commits
  2. Pointer updates require pushed commits - Remote must have the commit
  3. Prevents orphaned references - Master never points to unpushed commits

Conventional Commits​

All commits follow conventional commit format:

<type>(<scope>): <description>

<body>

🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>

Commit Types​

TypeUse For
featNew feature
fixBug fix
docsDocumentation only
refactorCode change that neither fixes nor adds
testAdding or updating tests
choreMaintenance tasks
ciCI/CD changes

Examples​

feat(agents): Add rust-expert-developer agent

docs(guides): Create troubleshooting guide

fix(scripts): Correct skills glob pattern

chore: Update submodule pointers

Submodule Management​

Check Submodule Status​

git submodule status

Update All Submodules​

git submodule update --init --recursive

Pull Latest in Submodule​

cd submodules/category/repo-name
git checkout main
git pull
cd ../../..
git add submodules/category/repo-name
git commit -m "chore: Update repo-name submodule"

Working with Worktrees​

For parallel work without branch conflicts:

# Create worktree for feature work
git worktree add ../feature-branch feature/new-feature

# Work in worktree
cd ../feature-branch
# ... make changes ...
git commit -m "feat: New feature"

# Remove worktree when done
git worktree remove ../feature-branch

Conflict Resolution​

Submodule Conflicts​

# Option 1: Use theirs (remote version)
cd submodules/conflicted
git checkout --theirs .
git add .
git commit -m "fix: Resolve conflict with remote"

# Option 2: Use ours (local version)
git checkout --ours .
git add .
git commit -m "fix: Resolve conflict with local"

# Option 3: Manual merge
git mergetool

Pointer Conflicts​

# Update to latest submodule commit
cd submodules/conflicted
git fetch
git checkout origin/main
cd ../..
git add submodules/conflicted
git commit -m "fix: Update submodule pointer to latest"

Pre-Push Verification​

Before pushing, verify:

# Check for uncommitted changes
git status

# Check submodule status
git submodule status | grep "^+"

# Verify all pointers are valid
git submodule foreach 'git status'

Automation Scripts​

sync-all-submodules.sh​

./scripts/sync-all-submodules.sh

Safely syncs all submodules handling detached HEAD states.

verify-distributed-intelligence.sh​

./scripts/verify-distributed-intelligence.sh

Verifies symlink chains are intact across repositories.

Best Practices​

  1. Always sync from clean state - Commit or stash local changes first
  2. Use dry-run first - Preview changes before executing
  3. Review commit messages - Ensure they follow conventions
  4. Push submodules before master - Bottom-up order is critical
  5. Verify after sync - Check git status in all repos

Last Updated: 2025-12-22 Owner: AZ1.AI INC