git-operations git:20261106.585f6d9A

Immutable. This exact content never changes and is served at /api/v1/blob/ac81fe4abf1030d8.

---
name: git-operations
description: "Git command patterns, branching strategy, and safety protocols. TRIGGER when: managing branches, resolving merge conflicts, or running commit/merge/push operations. SKIP: worktree lifecycle and isolation recovery (use worktree-management); CI automation (use github-actions-template)."
---

# Git Operations Skill

## Purpose
Core git command patterns, branching strategies, and safety protocols for a project.

Current branch: !`git branch --show-current 2>/dev/null || true`

## Branching Convention

| Branch Pattern | Purpose |
|----------------|---------|
| `main` | Production branch, always stable |
| `scaffolding/{task_id[:12]}` | Worktree task branches (auto-created) |
| `backup/{task_id[:12]}` | Safety backup before destructive ops |

## Safe Operation Patterns

### Before Any Destructive Operation
```bash
git status
git stash list
git log --oneline -5
git branch backup/$(date +%s) HEAD
```

### Merge Strategy
```bash
git merge --no-commit --no-ff branch_name
git diff --cached --stat
git merge --continue  # or --abort
```

### Conflict Resolution
```bash
git diff --name-only --diff-filter=U
git checkout --ours path/to/file    # keep ours
git checkout --theirs path/to/file  # keep theirs
```

### Cherry-Pick
```bash
git cherry-pick --no-commit <commit>
git diff --cached --stat
git cherry-pick --continue
```

## Common Error Patterns

| Error | Fix |
|-------|-----|
| `fatal: not a git repository` | Verify path, check .git exists |
| `CONFLICT (content)` | Use conflict resolution protocol |
| `cannot lock ref` | Wait and retry, check stale locks |
| `worktree is not clean` | Stage+commit or stash |

## Push Operations

### Standard Push (after workflow)
```bash
# 1. Verify unpushed commits exist
git log --oneline origin/main..HEAD

# 2. Push to remote
git push origin main

# 3. Verify push succeeded
git log --oneline origin/main..HEAD  # should be empty
```

### Push Safety Rules
- NEVER use `--force` or `--force-with-lease` without explicit user confirmation
- Always verify unpushed commits BEFORE push
- Always verify push success AFTER push
- If push fails due to divergence, report to user -- do NOT auto-rebase

## Finishing Flow

After work is complete on a branch, execute one of these four actions based on context.

### Merge to Main
```bash
git checkout main
git merge --ff-only <branch>  # try fast-forward first
# if ff fails: git merge --no-ff <branch>
# MANDATORY cleanup -- see Post-Merge Cleanup
```

### Post-Merge Cleanup (MANDATORY final step of every merge)
Applies to ff, `--no-ff`, and squash merges (PR merged via `gh`/Gitea too). Squash merges are invisible to `git branch --merged`.
```bash
# from the main checkout, never from inside the worktree
git -C <worktree> status --porcelain --untracked-files=no   # must be empty
git worktree remove <worktree>        # --force only for untracked build output (node_modules)
git branch -D <branch>
git worktree prune
```
- Uncommitted tracked changes -> REFUSE, keep worktree + branch, report the files.
- Never delete remote branches here. Never touch the main checkout.
- Put the result in the final report (Worktree Cleanup table).
- Stale leftovers: `/worktree-gc` (dry run by default).

### Create PR
```bash
git push -u origin <branch>
gh pr create --title "<title>" --body "<body>"
# keep branch and worktree
```

### Keep Branch
```bash
# no action needed -- branch stays as-is
git push -u origin <branch>  # optional: push to remote for safety
```

### Discard Branch
```bash
git checkout main
git worktree remove .scaffolding/worktrees/<task_id> 2>/dev/null
git branch -D <branch>
git worktree prune
```