/git-operations

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

git status
git stash list
git log --oneline -5
git branch backup/$(date +%s) HEAD

Merge Strategy

git merge --no-commit --no-ff branch_name
git diff --cached --stat
git merge --continue  # or --abort

Conflict Resolution

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

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)

# 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

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`.

# 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

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

Keep Branch

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

Discard Branch

git checkout main
git worktree remove .scaffolding/worktrees/<task_id> 2>/dev/null
git branch -D <branch>
git worktree prune