claudetools/.claude/skills/gitea

Gitea Skill — Bulletproof Git/Gitea Operations

Comprehensive git/Gitea operations extracted from sync.sh into reusable commands for the fleet.

Quick Start

# Fix a broken submodule (what you needed for radio-show)
bash .claude/skills/gitea/scripts/gitea.sh submodule fix projects/radio-show

# Health check before sync
bash .claude/skills/gitea/scripts/gitea.sh health

# Status with all submodules
bash .claude/skills/gitea/scripts/gitea.sh status --verbose

# Initialize all missing submodules
bash .claude/skills/gitea/scripts/gitea.sh submodule init

# Sync submodules to remote tips (opt-in, like --with-submodules)
bash .claude/skills/gitea/scripts/gitea.sh submodule sync

What This Solves

Problem: Manual Submodule Fixes

Before this skill, fixing a broken submodule like radio-show required:

1. Manually running git submodule init
2. Then git submodule update --init
3. Dealing with collision errors
4. Checking if it worked
5. Fixing detached HEADs

Now: bash .claude/skills/gitea/scripts/gitea.sh submodule fix projects/radio-show

Problem: Sync.sh Patterns Locked Away

The battle-tested patterns in sync.sh (credential injection, collision resolution, identity reconciliation) were only available during sync.

Now: Available as standalone commands for any git operation.

Problem: No Health Visibility

You'd only discover git issues when sync failed.

Now: bash .claude/skills/gitea/scripts/gitea.sh health proactively checks everything.

Integration with Existing Scripts

Using in sync.sh (Future Refactor)

Replace inline submodule handling with skill calls:

# Instead of 150 lines of submodule init/update logic:
bash .claude/skills/gitea/scripts/gitea.sh submodule init

# Instead of resolve_submodule_collisions + retry:
bash .claude/skills/gitea/scripts/gitea.sh submodule update

Using in Other Scripts

# Backup script needs health check before backup:
bash .claude/skills/gitea/scripts/gitea.sh health || exit 1

# Deployment script needs clean status:
bash .claude/skills/gitea/scripts/gitea.sh status --verbose

Commands Reference

Submodule Operations

Command	Use Case	What It Does
submodule init [PATH]	Fresh clone, new submodule added	Init & populate at pinned commit, inject creds, reconcile identity
submodule update [PATH]	After parent pull	Checkout to pinned commit, handle collisions
submodule sync [PATH]	Want latest upstream	Fetch + ff-merge to remote tip (opt-in)
submodule status	Check all submodules	Show status with color coding
submodule fix [PATH]	Any submodule issue	Auto-detect & fix common problems

Repository Operations

Command	Use Case	What It Does
status [--verbose]	Quick check	Show repo + optional submodule status
health	Pre-sync validation	Full diagnostic: identity, config, subs, remote
fetch [--recurse]	Inspect before pull	Fetch from origin, optional submodule recursion
pull [--recurse]	Sync from remote	Fetch + rebase, update subs after
push	Publish work	Push to origin/main
commit "msg"	Commit staged changes	Simple commit wrapper

Utilities

Command	Use Case	What It Does
verify-identity	Fix git config drift	Reconcile user.name/email from identity.json
inject-creds	Submodule auth issues	Inject parent HTTPS creds to submodules

Error Codes

• 0 — Success
• 1 — General error (bad args, command failed)
• 2 — identity.json missing/unreadable
• 3 — Not a git repo
• 75 — Lock contention (reserved for future use)

Common Workflows

1. Fix Broken Submodule (Like radio-show)

bash .claude/skills/gitea/scripts/gitea.sh submodule fix projects/radio-show

Detects and fixes:

• Not initialized
• Detached HEAD
• Colliding untracked files
• Pointer mismatch with parent

2. Pre-Sync Health Check

if bash .claude/skills/gitea/scripts/gitea.sh health; then
    bash .claude/scripts/sync.sh
else
    echo "Fix issues first"
fi

3. Initialize All Submodules on Fresh Clone

bash .claude/skills/gitea/scripts/gitea.sh submodule init

Auto-injects credentials, reconciles identity, handles all 22 submodules.

4. Advance Submodules to Remote Tips

# Like sync.sh --with-submodules, but standalone
bash .claude/skills/gitea/scripts/gitea.sh submodule sync

5. Debug Submodule Issues

# See what's wrong
bash .claude/skills/gitea/scripts/gitea.sh submodule status

# Try auto-fix
bash .claude/skills/gitea/scripts/gitea.sh submodule fix

# Still broken? Manual intervention with context

Fleet Deployment

Current Status

• Skill created and tested on Mikes-MacBook-Air
• Works with existing identity.json
• No changes required to sync.sh (but refactor recommended)

Rollout Plan

1. Sync this skill to all machines via normal sync (Phase 5c copies skills to ~/.claude/skills)
2. Test health command on each machine
3. Document any machine-specific issues
4. Optionally refactor sync.sh to use skill helpers
5. Train team on common commands

Testing Checklist

• gitea.sh health runs successfully
• gitea.sh submodule status shows all submodules
• gitea.sh submodule fix resolves issues
• gitea.sh verify-identity matches identity.json
• Works on Windows (test garbled path handling)
• Works on Linux
• Works on macOS (tested ✓)

What's Extracted from sync.sh

This skill encapsulates:

• reconcile_git_identity() — now verify-identity command
• resolve_submodule_collisions() — used in update and fix
• inject_credentials() — now inject-creds command
• Submodule init/update/sync logic — now dedicated commands
• Health checks — new health command
• Python detection — reused from sync.sh
• identity.json loading — reused from sync.sh

Future Enhancements

Potential Additions

• gitea.sh submodule detach <path> — revert to pinned commit (undo accidental advance)
• gitea.sh bisect — wrapper for git bisect with submodule awareness
• gitea.sh blame <file> — enhanced blame with submodule context
• gitea.sh clone <url> — clone with auto credential injection
• Lock integration — claim sync lock via coord API

Integration Opportunities

• Call from sync.sh to deduplicate logic
• Call from backup scripts for pre-backup health
• Call from deployment scripts for clean-state validation
• Coord API integration for fleet-wide submodule status

Troubleshooting

Command Not Found

# Skill not synced yet
bash .claude/scripts/sync.sh  # Copies to ~/.claude/skills

# Or run directly from repo
bash /path/to/ClaudeTools/.claude/skills/gitea/scripts/gitea.sh health

identity.json Errors

# Check identity.json exists and is valid JSON
cat .claude/identity.json | python3 -m json.tool

Submodule Fix Not Working

# Check what's actually wrong
bash .claude/skills/gitea/scripts/gitea.sh submodule status

# Try manual intervention
cd projects/problematic-submodule
git status
git log --oneline -5

Credential Injection Not Working

# Check parent URL has embedded credentials
git config --get remote.origin.url

# Should be: https://user:pass@host/repo.git
# Not: https://host/repo.git or git@host:repo.git

See Also

• .claude/scripts/sync.sh — The main sync script this skill extends
• .claude/CLAUDE_EXTENDED.md — Full ClaudeTools manual
• .gitmodules — Submodule configuration
• wiki/systems/gitea.md — Gitea server documentation (if exists)