| 1 | # Git Workflow Playbook v1 |
| 2 | |
| 3 | ## Purpose |
| 4 | |
| 5 | Provide a stable, low-risk Git operating model for daily development, review, and recovery. |
| 6 | |
| 7 | ## Core Workflow |
| 8 | |
| 9 | 1. Inspect local state: `status -> diff -> staged diff`. |
| 10 | 2. Stage only logical scope of change. |
| 11 | 3. Commit with message explaining intent and impact. |
| 12 | 4. Re-check local state after commit. |
| 13 | 5. Push branch and verify remote state. |
| 14 | |
| 15 | ## Branching Contract |
| 16 | |
| 17 | - Keep `main` protected and stable. |
| 18 | - Create feature/fix branches for non-trivial changes. |
| 19 | - Keep branch scope single-purpose (avoid mixed-domain commits). |
| 20 | - Prefer short-lived branches with frequent synchronization. |
| 21 | |
| 22 | ## Commit Contract |
| 23 | |
| 24 | - One logical change per commit. |
| 25 | - Message must answer: **why now** and **what behavior changed**. |
| 26 | - Avoid “dump” commits that mix refactor + feature + docs unless tightly coupled. |
| 27 | - Re-run minimal validation before final commit. |
| 28 | |
| 29 | ## Identity and Shell Contract (Windows) |
| 30 | |
| 31 | - Identity resolution order follows Git commit rules: |
| 32 | - environment: `GIT_AUTHOR_*` / `GIT_COMMITTER_*`; |
| 33 | - config: `author.*` / `committer.*`; |
| 34 | - config fallback: `user.name` / `user.email`; |
| 35 | - last fallback: `EMAIL`, then system user + hostname. |
| 36 | - For routine Windows workflows, prefer native shell (`PowerShell`/`cmd`) for `git commit`. |
| 37 | - Treat cross-shell commit runs (`bash -lc`, MSYS/MinGW, WSL) as explicit context switch. |
| 38 | - Before commit in a switched shell, verify identity with: |
| 39 | - `git config --show-origin --get user.name` |
| 40 | - `git config --show-origin --get user.email` |
| 41 | - `git var GIT_AUTHOR_IDENT` |
| 42 | - If shell context still disagrees, use one-shot fallback: |
| 43 | - `git -c user.name=\"...\" -c user.email=\"...\" commit ...` |
| 44 | |
| 45 | ## Review Contract |
| 46 | |
| 47 | - Start review from risk: behavior regressions, data loss, safety boundaries. |
| 48 | - Validate test impact and missing checks. |
| 49 | - Call out uncertainty explicitly. |
| 50 | - Use small diffs and deterministic reproduction steps. |
| 51 | |
| 52 | ## Safety Rules |
| 53 | |
| 54 | - Never use destructive commands on shared branches by default. |
| 55 | - Never force-push shared `main/master` history. |
| 56 | - Do not rewrite published history unless explicitly approved. |
| 57 | - Treat credential files and tokens as non-committable by policy. |
| 58 | |
| 59 | ## Recovery Patterns |
| 60 | |
| 61 | - Uncommitted recovery: `git restore --staged` / selective restore by file. |
| 62 | - Lost pointer recovery: `git reflog` first, then recover target commit. |
| 63 | - Bad merge recovery: abort/reset strategy based on publication state. |
| 64 | - Always prefer reversible path before irreversible cleanup. |
| 65 | |
| 66 | ## Operational Cadence |
| 67 | |
| 68 | - Before starting work: quick `status` + branch check. |
| 69 | - Before context switch: checkpoint commit or explicit stash with note. |
| 70 | - End of session: clean working tree or explicit WIP marker. |
| 71 | |
| 72 | ## Revisit Triggers |
| 73 | |
| 74 | - Recurring merge conflicts in same area. |
| 75 | - Frequent “mixed commits” that block review quality. |
| 76 | - Recovery actions needed more than once per week. |
| 77 | |
| 78 | |