claudetools/.claude/skills/gitea/SKILL.md

name, description

name	description
gitea	Comprehensive git/Gitea operations for ClaudeTools fleet: submodule management (init/update/sync/fix), status checks, commit/push/pull with proper error handling, credential injection, identity reconciliation. Makes sync/save bulletproof across all machines. Triggers: git submodule, gitea, fix submodule, git sync, submodule issues, clone repo, git status, repo health.

gitea — Bulletproof git/Gitea operations

One skill for all git/Gitea operations across the fleet. Encapsulates the patterns from sync.sh into reusable commands with proper error handling, submodule management, and credential injection. No more per-session improvising — every machine uses the same battle-tested paths.

Core commands

# Submodule operations
bash .claude/skills/gitea/scripts/gitea.sh submodule init [PATH]      # Init one or all submodules
bash .claude/skills/gitea/scripts/gitea.sh submodule update [PATH]    # Update to pinned commit
bash .claude/skills/gitea/scripts/gitea.sh submodule sync [PATH]      # Fetch + advance to remote tip
bash .claude/skills/gitea/scripts/gitea.sh submodule status           # Show all submodule status
bash .claude/skills/gitea/scripts/gitea.sh submodule fix [PATH]       # Auto-fix common issues

# Repository operations
bash .claude/skills/gitea/scripts/gitea.sh status [--verbose]         # Repo + submodule status
bash .claude/skills/gitea/scripts/gitea.sh fetch [--recurse]          # Fetch from origin
bash .claude/skills/gitea/scripts/gitea.sh pull [--recurse]           # Pull with rebase
bash .claude/skills/gitea/scripts/gitea.sh push                       # Push to origin
bash .claude/skills/gitea/scripts/gitea.sh commit "<msg>"             # Commit staged changes

# Health & diagnostics
bash .claude/skills/gitea/scripts/gitea.sh health                     # Full repo health check
bash .claude/skills/gitea/scripts/gitea.sh verify-identity            # Check git identity
bash .claude/skills/gitea/scripts/gitea.sh inject-creds               # Inject parent creds to subs

What it handles for you

Submodule management

• Init with credential injection — inherits HTTPS credentials from parent origin URL
• Collision detection — moves aside untracked files that block checkout (preserves content)
• Identity reconciliation — sets git user.name/email from identity.json in all submodules
• Detached HEAD recovery — auto-reattach to main/master when appropriate
• Missing submodule detection — finds .gitmodules entries without working trees

Error handling

• Transient failures — retries submodule updates with collision resolution
• Dead gitlink refs — graceful degradation when historical commits are force-pushed-out
• Concurrent lock conflicts — detects and reports when another sync is running
• Network failures — clear error messages with recovery hints

Fleet conventions

• Identity.json reconciliation — forces git config to match on every operation
• Selective submodule advance — respects pinned-commit-lagging-main pattern unless opted in
• Windows path cruft — detects and warns about garbled path-as-filename issues
• Credential reuse — HTTPS auth from parent propagates to all submodules

Common workflows

Fix a broken submodule

# Single command — detects and fixes: missing init, detached HEAD, collisions, stale pointers
bash .claude/skills/gitea/scripts/gitea.sh submodule fix projects/radio-show

This is what you needed for radio-show — one command instead of manual git submodule update --init.

Check health before sync

# Catches: stale identity, missing submodules, uncommitted changes, detached HEADs, dead refs
bash .claude/skills/gitea/scripts/gitea.sh health

Safe submodule advance (opt-in)

# Fetch + ff-merge all submodules to their remote tips (sync.sh --with-submodules equivalent)
bash .claude/skills/gitea/scripts/gitea.sh submodule sync

Status across everything

# Parent + all submodules in one view (colored, formatted)
bash .claude/skills/gitea/scripts/gitea.sh status --verbose

When to use each command

Command	When to use	What it does
submodule init	Fresh clone, missing submodule	Register + populate at pinned commit
submodule update	After parent pull, pointer changed	Checkout to pinned commit
submodule sync	Want latest upstream (opt-in)	Fetch + advance to remote tip
submodule fix	Any submodule issue	Detect + auto-fix common problems
submodule status	Check what's going on	Show all submodules + state
status	Quick health check	Parent + subs, uncommitted changes
health	Pre-sync validation	Full diagnostic scan
fetch	Inspect before pull	Get remote refs, no merge
pull	Sync from remote	Fetch + rebase + update subs
push	Publish local work	Push to origin/main

Integration with sync.sh

sync.sh already implements most of this internally. This skill extracts those patterns into reusable commands for:

• Manual submodule fixes outside of sync
• Pre-sync health checks
• Debugging git issues
• Other scripts that need git operations (e.g., backup, deployment)

You can refactor sync.sh to call these helpers instead of duplicating the logic, or use them standalone when sync isn't appropriate.

Error codes

• 0 — success
• 1 — general error (bad args, git command failed)
• 2 — identity.json missing or unreadable
• 3 — not a git repo
• 75 — lock contention (another sync running)

Notes

• All submodule operations reconcile git identity from .claude/identity.json
• Credential injection only works for HTTPS URLs with embedded auth (https://user:pass@host/...)
• The --recurse flag on fetch/pull is opt-in (default: no submodule recursion)
• Health check output is colored (green=ok, yellow=warning, red=error) and machine-parseable
• All commands are idempotent and safe to re-run