azcomputerguru/claudetools
1
0
Fork 0
Code Issues 58 Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add gitea skill for bulletproof git/submodule operations

Browse Source 
Comprehensive git/Gitea operations skill extracting battle-tested patterns from
sync.sh into reusable commands for the fleet. Makes submodule management,
status checks, and common git operations bulletproof across all machines.

Core features:
- Submodule operations: init, update, sync, status, fix
- Repository operations: status, health, fetch, pull, push, commit
- Utilities: verify-identity, inject-creds
- Auto-fixes: collision resolution, detached HEAD recovery, identity reconciliation
- Proper error handling with meaningful exit codes

Key fixes from sync.sh patterns:
- Credential injection from parent to submodules
- Untracked file collision resolution (preserves content)
- Identity reconciliation from identity.json
- Graceful degradation for transient failures

Usage examples:
  bash .claude/skills/gitea/scripts/gitea.sh submodule fix projects/radio-show
  bash .claude/skills/gitea/scripts/gitea.sh health
  bash .claude/skills/gitea/scripts/gitea.sh status --verbose

This fixes the radio-show submodule issue and provides tools for future git
operations without manual intervention.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Mike Swanson
2026-06-20 08:44:47 -07:00
parent d2f9a96d8f
commit 354754e5df
3 changed files with 953 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

250
.claude/skills/gitea/README.md Normal file
View File

@@ -0,0 +1,250 @@
# Gitea Skill — Bulletproof Git/Gitea Operations
Comprehensive git/Gitea operations extracted from `sync.sh` into reusable commands for the fleet.
## Quick Start
```bash
# 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:
```bash
# 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
```bash
# 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
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
```bash
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
bash .claude/skills/gitea/scripts/gitea.sh submodule init
```
Auto-injects credentials, reconciles identity, handles all 22 submodules.
### 4. Advance Submodules to Remote Tips
```bash
# Like sync.sh --with-submodules, but standalone
bash .claude/skills/gitea/scripts/gitea.sh submodule sync
```
### 5. Debug Submodule Issues
```bash
# 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
```bash
# 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
```bash
# Check identity.json exists and is valid JSON
cat .claude/identity.json | python3 -m json.tool
```
### Submodule Fix Not Working
```bash
# 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
```bash
# 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)