git-workflow ยท diff
git:20260812.4160717 to git:20260819.d23bb73
8 added, 8 removed. Audit A to A.
---
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](file:///Users/Devesh_Padmanabhan/.cursor/agent-engineering-handbook/rules/130-git.mdc) and [the agent audit rule](file:///Users/Devesh_Padmanabhan/.cursor/agent-engineering-handbook/rules/020-agent-audit.mdc).
+ 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](file:///Users/Devesh_Padmanabhan/.cursor/agent-engineering-handbook/skills/git-workflow/git-workflow.md).
+ 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](file:///Users/Devesh_Padmanabhan/.cursor/agent-engineering-handbook/skills/git-workflow/git-reflog.md).
+ 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](file:///Users/Devesh_Padmanabhan/.cursor/agent-engineering-handbook/skills/git-workflow/git-fundamentals.md) - refs, remotes, fetch/pull, and branch workflows
- - [Git workflow](file:///Users/Devesh_Padmanabhan/.cursor/agent-engineering-handbook/skills/git-workflow/git-workflow.md) - commits, signing, branches, PRs, and repository hygiene
- - [Modern Git commands](file:///Users/Devesh_Padmanabhan/.cursor/agent-engineering-handbook/skills/git-workflow/git-modern-commands.md) - `switch`, `restore`, moves, and worktrees
- - [Reflog](file:///Users/Devesh_Padmanabhan/.cursor/agent-engineering-handbook/skills/git-workflow/git-reflog.md) - recovery and history inspection
- - [Pre-commit](file:///Users/Devesh_Padmanabhan/.cursor/agent-engineering-handbook/skills/git-workflow/git-pre-commit.md) - hook setup and maintenance
+ - 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