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

---
name: gitea
description: >
  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

```bash
# 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

```bash
# 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

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

### Safe submodule advance (opt-in)

```bash
# 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

```bash
# 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