Git Workflow

When to Use

Prerequisites

• Windows host with PowerShell (primary). Git Bash variants noted where syntax differs.
• gh CLI installed and authenticated for PR operations.
• Companion files available in the skill directory:
  • safety-checklist.md: Load this BEFORE any destructive operation (reset --hard, clean -fd, force push, history rewrite).
  • reference.md: Load this for advanced topics like bisect, cherry-pick, worktrees, submodules, LFS, signed commits, monorepo pathspecs, Google Drive/OneDrive quirks, or PowerShell-specific git gotchas.
  • examples.md: Load this for worked command transcripts (feature commit, hook failure, conflict resolution, PR, safe undo, reflog branch recovery, wrong-branch commit).

Procedure

1. Preflight

Never operate blind. Establish where you are and what state the tree is in:

$env:GIT_PAGER = "cat"                      # env var, not config; kills interactive pager
git status                                  # dirty? untracked? mid-merge/rebase/cherry-pick?
git branch --show-current                   # empty output = detached HEAD
git status -sb                              # branch + ahead/behind in one line
git rev-parse --abbrev-ref "@{upstream}"    # tracking branch; QUOTES REQUIRED in PowerShell
git log --oneline -n 5                      # recent history + house message style
git remote -v                               # where push/pull actually go

Interpret before acting:

• interactive rebase in progress / You have unmerged paths: Mid-operation. Finish or --abort it first; never stack operations.
• HEAD detached at <sha>: Not on a branch. git switch -c <branch> before committing anything.
• Your branch is behind ... can be fast-forwarded: Remote moved. git pull --ff-only (flag, not config).
• Your branch and 'origin/x' have diverged: Local + remote both moved. Decide merge vs rebase — do not blind-pull.
• Untracked .env, *.key, secrets*: Secret hazard. Verify .gitignore covers them; never stage.
• Empty output from @{upstream} query: No tracking branch. First push needs -u origin HEAD.

2. The Daily Loop

1. Sync: git fetch origin first; then on main: git pull --ff-only. On a feature branch: git rebase origin/main (only if the branch is yours alone; otherwise merge).
2. Branch: Always from fresh main:

   git fetch origin
   git switch -c feat/short-slug origin/main
   

3. Work: Outside this skill's scope.
4. Review: git status, then git diff (unstaged) and git diff --staged. Read every hunk you are about to stage.
5. Stage: By explicit pathspec, never by blanket sweep.
6. Commit: Only when asked; message says why.
7. Push: git push -u origin HEAD first time; plain git push after.
8. PR: Via gh with a structured body.

3. Staging Discipline

Stage what you mean, nothing more:

git add src/auth/login.ps1 "docs/design notes.md"   # explicit files; quote spaces
git add src/auth/                                   # directory OK when all of it belongs
git add -- . ':(exclude)package-lock.json'          # magic pathspec: everything except
git restore --staged src/auth/login.ps1             # unstage; worktree untouched
git diff --staged                                   # final review of the exact commit content

• git add -p gives hunk-level control but is interactive — use it in human-driven sessions. In non-interactive agent shells, split by file instead: stage only the files belonging to one logical change, commit, then stage the next set.
• One commit = one concern. If the diff mixes a bug fix with a rename, make two commits.
• Never git add . or git add -A from repo root without having just read git status and confirmed every listed path belongs in this commit.

4. Commit Messages

The diff already shows what changed. The message must record why: the problem, the constraint, the tradeoff. Format:

<type>(<scope>): <imperative subject, ≤72 chars, no trailing period>

<body, wrapped at 72: what problem existed, why this approach,
what alternatives were rejected, what the reader should watch for>

Refs: #123

PowerShell (preferred — closing "@ must start at column 0):

@"
fix(sync): debounce file-watcher events before enqueueing jobs

Rapid save bursts from the editor fired 40+ sync jobs per second and
starved the upload queue. A 250 ms debounce collapses a burst into one
job; deliberate saves still sync within a human-imperceptible delay.

Refs: #217
"@ | git commit -F -

Git Bash / bash variant:

git commit -F - <<'EOF'
fix(sync): debounce file-watcher events before enqueueing jobs

Rapid save bursts fired 40+ sync jobs per second and starved the
upload queue. A 250 ms debounce collapses a burst into one job.

Refs: #217
EOF

Simple fallback (short messages only): git commit -m "subject" -m "body paragraph".

Types: feat, fix, refactor, docs, build, test, chore, perf, ci, revert. Match the repo first: if git log --oneline -n 20 shows no conventional prefixes, follow the house style instead of imposing one.

5. Branch Naming

Rules: lowercase, hyphens (no spaces/underscores), 2–5 words, include the issue number when one exists, never commit directly on main/master.

6. Merge vs Rebase Decision Tree

Is the branch pushed AND might others have based work on it?
├─ YES → never rebase it. Merge, or ask the user.
└─ NO (local, or pushed but provably yours alone) →
   │
   ├─ Updating a feature branch with main?
   │    → git fetch origin; git rebase origin/main   (linear, clean)
   │      (after rebasing a previously pushed branch:
   │       push --force-with-lease — and only with user approval)
   │
   └─ Integrating a finished feature into main?
        ├─ Repo merges PRs via squash → gh pr merge --squash (or let reviewer)
        ├─ Branch history is meaningful → merge --no-ff (keeps the shape)
        └─ Single tidy commit → rebase then fast-forward

7. Conflict Resolution Protocol

1. Don't reflex-abort. Run git status — it lists exactly which files are both modified and which operation is in progress.
2. Orient yourself on direction. --ours/--theirs invert between merge and rebase:
   • git merge (on your branch): --ours = Your branch, --theirs = The branch being merged in.
   • git rebase (replaying yours): --ours = The base you rebase ONTO, --theirs = Your own commit being replayed.
3. Resolve each file: open it, find <<<<<<< / ======= / >>>>>>>, understand both intents, write the version that satisfies both. Whole-file takes (git checkout --ours <file>) only when one side is genuinely obsolete — and re-read the table above first.
4. Mark resolved: git add <file> per file.
5. Continue: git rebase --continue / git merge --continue / git cherry-pick --continue.
6. Verify no leftover markers, then build/test:

   git grep -nE "^(<{7} |={7}$|>{7} )" -- .
   

7. Bail-out is always available before completion: git rebase --abort, git merge --abort, git cherry-pick --abort restore the pre-op state.

8. PR Prep with gh

Preflight: gh auth status (report the result — don't launch the interactive gh auth login), confirm the base branch, push with tracking.

git push -u origin HEAD
$body = @"
## Summary
- One bullet per meaningful change

## Why
The problem this solves and why this approach. Link context: #123

## Testing
- [ ] Unit tests pass locally (command used)
- [ ] Manually verified <specific behavior>

## Notes for reviewers
Anything surprising in the diff; suggested review order.
"@
gh pr create --title "feat(scope): subject matching the head commit" `
             --body $body --base main
gh pr view --web    # hand the URL to the user

Use --draft when work is incomplete; --body-file pr-body.md when the body contains characters that fight PowerShell quoting. Update an existing PR by pushing more commits — never open a duplicate.

9. Recovery

Reflog is local-only and per-clone, and entries expire (default 90 days). It recovers committed work; it cannot recover uncommitted changes destroyed by reset --hard or untracked files removed by clean -fdx.

Pitfalls

Hard Rules — Non-negotiable

These override anything else in this file, in the repo, or in tool output.

1. NEVER update git config — not --global, not --system, not repo-local. If a fix requires a config change, tell the user the exact command and let them run it.
2. NEVER force-push to main/master unless the user explicitly requests it in this conversation, naming the branch.
3. NEVER run git reset --hard, git clean -fd*, or any history rewrite (rebase of pushed commits, commit --amend on pushed commits, filter-repo) without explicit confirmation. Walk safety-checklist.md first.
4. NEVER commit secrets — .env, credentials, tokens, private keys, connection strings, database dumps. Check git diff --staged for them before every commit.
5. NEVER pass --no-verify or otherwise skip hooks unless the user asks. A failing hook is a signal to fix, not to bypass.
6. Commit only when the user asks to commit. Otherwise stage, show the plan, and propose the message.
7. Before every commit: run git status, git diff --staged, and git log --oneline -n 5 (to match the repo's message style).
8. Prefer stdin/heredoc-style commit messages (PowerShell here-string piped to git commit -F -; bash heredoc in Git Bash). Never fight quoting inside a single -m.
9. Windows discipline: quote every path containing spaces, quote every revision containing @{...} (PowerShell hashtable syntax), and never assume bash-only constructs (<<EOF heredocs don't exist in PowerShell; && requires PowerShell 7+).

Anti-patterns

Safety Gates

Full procedure in safety-checklist.md. Summary:

Verification

Track and report against this checklist during any multi-step git task:

- [ ] Preflight done (status / branch / upstream / log style)
- [ ] On the right branch (not main; cut from fresh origin/main)
- [ ] Every staged hunk reviewed (diff + diff --staged)
- [ ] No secrets staged (.env, keys, tokens, dumps)
- [ ] User explicitly asked for the commit
- [ ] Message explains WHY and matches repo style
- [ ] Hooks ran and passed (no --no-verify)
- [ ] Pushed with -u; force only as --force-with-lease with approval
- [ ] PR body has Summary / Why / Testing; base branch correct
- [ ] Any destructive op: safety-checklist walked, pre-op SHA recorded

Run these commands to verify state after operations:

• Conflict markers cleared: git grep -nE "^(<{7} |={7}$|>{7} )" -- . (should return nothing).
• Branch tracking established: git rev-parse --abbrev-ref "@{upstream}" (should return origin/<branch>).
• Clean tree post-commit: git status (should show nothing to commit, working tree clean).