---
name: git-workflow
description: Safe Git workflows for commits, branches, worktrees, recovery, signing, and remote synchronization. Use when creating or reviewing commits, branching, pushing, rebasing, restoring files, resolving divergence, using worktrees, or asking how Git behaves.
---

# Git Workflow

Use this skill for Git procedures. Mandatory authorization and preservation gates remain in the Git rule (`${HANDBOOK_ROOT}/rules/130-git.mdc`) and the agent audit rule (`${HANDBOOK_ROOT}/rules/020-agent-audit.mdc`).

## Non-Negotiable Workflow

1. Inspect the repository before changing it:

   ```bash
   git status --short --branch
   git branch --show-current
   git rev-parse HEAD
   ```

2. Preserve unrelated user changes. Never discard, stash, rewrite, or relocate them merely to simplify the task.
3. Treat commit, push, force update, history rewrite, restore/discard, destructive branch deletion, and worktree removal as separate authorization boundaries.
4. Run applicable tests, lint, formatting, type checks, and build steps before proposing a commit.
5. Before committing, show the complete message and exact file list, then wait for explicit confirmation.
6. Respect repository signing policy. If signing fails, stop; never silently create an unsigned commit.
7. Before pushing, fetch with pruning and inspect upstream divergence. Do not blindly pull, rebase, merge, or force-push.

## Common Workflows

### Create a feature branch

Start from a refreshed remote base.

For a clean worktree:

```bash
git fetch origin --prune
git switch main
git pull --ff-only
git switch -c feat/your-feature
```

When the current worktree has unrelated changes, preserve it and create an isolated worktree:

```bash
git fetch origin --prune
git worktree add -b feat/your-feature ../project-your-feature origin/main
```

Do not use `git switch -c` in a dirty worktree: compatible uncommitted changes can follow the new branch.

### Prepare a commit

Inspect status, staged and unstaged changes, and recent message style. Stage only the approved files. Use the format and review gate in git-workflow.md (`${HANDBOOK_ROOT}/skills/git-workflow/git-workflow.md`).

### Push an existing branch

```bash
git fetch origin --prune
git status --short --branch
git log --oneline --left-right --boundary HEAD...@{upstream}
```

- Ahead only: push after authorization.
- Behind only: fast-forward only when repository policy permits.
- Diverged: stop and choose merge or rebase based on repository policy and whether commits are shared.
- Dirty worktree: do not rebase or merge until unrelated work is understood and preserved.

Use `git push -u origin HEAD` only for a new branch without an upstream. Never force-push unless that exact update was explicitly authorized; never force-push a protected default branch.

### Recover safely

Inspect reflog and repository state before choosing a recovery operation. Prefer creating a recovery branch or restoring a specific object over destructive reset. See git-reflog.md (`${HANDBOOK_ROOT}/skills/git-workflow/git-reflog.md`).

## References

- Git fundamentals (`${HANDBOOK_ROOT}/skills/git-workflow/git-fundamentals.md`) - refs, remotes, fetch/pull, and branch workflows
- Git workflow (`${HANDBOOK_ROOT}/skills/git-workflow/git-workflow.md`) - commits, signing, branches, PRs, and repository hygiene
- Modern Git commands (`${HANDBOOK_ROOT}/skills/git-workflow/git-modern-commands.md`) - `switch`, `restore`, moves, and worktrees
- Reflog (`${HANDBOOK_ROOT}/skills/git-workflow/git-reflog.md`) - recovery and history inspection
- Pre-commit (`${HANDBOOK_ROOT}/skills/git-workflow/git-pre-commit.md`) - hook setup and maintenance