Git Hygiene

Git Hygiene

Rules

• link associated Linear issues (e.g., XY-123) when committing (when present)
• keep local work on main; use PR branches only for review/delivery when asked
  • I am a one man team, working too fast to deal with endless PRs and branches
• prefer atomic commits: only committing your work, listing paths explicitly and checking the code for changes from other agents
  • prefer explicit paths (or git add -p) over git add .
  • quote paths containing brackets/parentheses so the shell doesn't treat them as globs/subshells.
• do not let a dirty working tree block progress
  • commit only staged changes (your files); ignore other dirty files
  • never stage/commit someone else’s changes “just to clean things up”
  • avoid operations that require a clean working tree (rebases, non-ff merges) unless explicitly needed
• commit by default
  • Do not push or open PRs unless the user explicitly asks for it
• do not run destructive git ops (git reset --hard, force pushes, etc.) unless explicitly instructed
• Before deleting files (or using deletion to "fix" tests/lint), stop and ask
• never discard file content you didn't author (e.g., git restore <path>, git checkout -- <path>) unless explicitly instructed
• git restore --staged ... is allowed for staging hygiene (it does not discard working tree changes)
• always double-check git status before and after each commit

Dirty Working Tree (Multi-Agent Reality)

Goal: keep shipping without stepping on other agents.

• You can always commit your work while other files are dirty: stage only your paths, then commit.
• Prefer fetch-only “sync” (git fetch origin --prune). It never touches the working tree.
• Avoid rebasing and avoid merging origin/main into a dirty working tree unless explicitly required (e.g., GitHub shows unavoidable conflicts / branch protection requires up-to-date).

Remote Sync (origin/main)

Default: stay productive. Fetch for awareness. Only “integrate” when necessary.

• Always safe: git fetch origin --prune
• Avoid git pull by default (it bakes in merge/rebase behavior that’s easy to forget).
  • If you ever run git pull and it blocks/conflicts: do not stash or commit random work “to unblock”. Stop and ask Ian for input.
• Prefer merge commits on PR merge (see Commit + PR Workflow) so local commits keep their SHAs.

1. Refresh your view of remote
   • git fetch origin --prune
2. Check divergence
   • git rev-list --left-right --count origin/main...HEAD
   • Output is <behind> <ahead> (how many commits you are behind/ahead of origin/main)
3. Pick the safe action
   • behind>0 and ahead=0: optional fast-forward (only if the working tree is clean)
     • git merge --ff-only origin/main
   • behind=0 and ahead>0: you’re ahead locally; OK to keep committing locally
   • behind>0 and ahead>0: you have local commits and origin/main moved
     • default: do nothing; keep committing your work; publish via PR branch when asked
     • avoid rebasing local main (rewrites history) unless explicitly instructed

Modes

• Commit-only (default): create atomic commits locally.
• Commit + PR (only when explicitly requested): create atomic commits, push to a pr/... branch, open PR, optionally trigger AI review, and (optionally) merge.

Commit Messages

Use a conventional prefix, then a concise summary. If a Linear issue exists, include it consistently.

• prefixes: feat:, fix:, refactor:, docs:, chore:, agents:
• preferred issue format: append in parentheses: ... (XY-123)

Staging Cookbook

Keep these moves in muscle memory:

• stage interactively: git add -p
• stage explicit paths: git add path/to/file.ts path/to/other.ts
• unstage (keep edits): git restore --staged path/to/file.ts
• amend last commit (local only): git commit --amend
• inspect staged-only scope: git diff --staged --name-only

Commit Workflow (DEFAULT)

1. Snapshot state + sanity-check scope
   • git status -sb
   • git diff
   • git diff --staged
   • git diff --staged --name-only
   • git diff --name-only (optional; useful to spot other-agent edits you should ignore)
   • git log -5 --oneline
2. Refresh remote view (cheap)
   • git fetch origin --prune
3. Propose a commit plan
   • Group changes by issue or intent & suggest commit titles (see Commit Messages above)
   • Call out anything ambiguous and ask before proceeding
4. Execute commits one by one
   • Stage minimally (git add -p or explicit paths)
   • Avoid git add . unless the user explicitly asks for a "one big commit"
   • Run the smallest relevant verification (tests / lint / build)
   • Write a clear message; include linked issue IDs when applicable (Linear/GitHub)
5. Final check
   • Confirm your intended changes are committed (or explain what remains dirty)
   • Summarize what each commit contains + any follow-ups

Commit + PR Workflow (WHEN REQUESTED)

1. Do the Commit workflow above first
2. Fetch before publishing
   • git fetch origin --prune
   • git rev-list --left-right --count origin/main...HEAD
   • If you are behind>0 and ahead=0 and the working tree is clean: optionally fast-forward (git merge --ff-only origin/main)
   • Otherwise: do not block; proceed to publish PR branch
3. Push to a PR branch (without switching branches)
   • Branch naming: pr/<short-description>
   • git push origin HEAD:pr/<short-description>
4. Create PR: prefer non-interactive creation and self-assigning:
   • gh pr create --head pr/<short-description> --base main --assignee @me --fill
5. Review loop: set a 5 minute timeout and then check the PR’s GitHub comments for AI code-review agent feedback (automatically triggered on PR creation)
   • if straightforward/clear, do yourself and commit/push; if unclear/opinionated, ask for feedback
   • repeat review loop until satisfactory (check-in if repeated issues)
6. Merge: once everything looks good, provide a summary and ask for merge approval
   • prefer merge commits to avoid rewriting commit SHAs (keeps local main compatible with origin/main):
     • gh pr merge --merge --delete-branch
   • if blocked (required reviews/checks), leave a handoff with PR number + what's missing

Rebase Safety

If rebasing is required, avoid interactive editor prompts:

• prefer scoping to a single command (avoid persistent shell env changes):
  • GIT_EDITOR=: GIT_SEQUENCE_EDITOR=: git rebase origin/main
• (or use --no-edit when safe)