Skip to content

Parallel-Safe Git Rules

Multiple Copilot CLI sessions, VS Code instances, and AI bots can all be modifying the same repo at the same time. These rules exist because git add . and git commit -a are landmines in that environment.

The four rules

Rule 1 — Always explicit paths

Never git add . or git add -A or git commit -a. Always git add <path1> <path2>.

# WRONG — sweeps in WIP from other sessions
git add .
git commit -m "..."

# RIGHT — explicit, predictable, scope-limited
git add docs/reference/deployment-playbook.md docs/reference/parallel-git-rules.md
git commit -m "..."

The . and -A flags grab every modified file in the working tree — including files another session is still editing but hasn't staged. That session's WIP ships under your commit message.

Rule 2 — Read git status -s before every commit

Before staging anything, check the porcelain output:

M  docs/reference/index.md     ← capital M, leading SPACE = staged by something else
 M docs/zen-system/colours.md  ← lowercase letter, leading SPACE = unstaged change YOU own
A  docs/reference/new-page.md  ← A in first column = staged by you (just-added file)
?? docs/zen-system/scratch.md  ← untracked

The character in column 1 is the index state; column 2 is the working tree. M (M then space) means already in the index — staged by someone (probably another session). If you didn't stage it yourself, stop.

git restore --staged docs/path/that/isnt/yours.md

Rule 3 — Verify what's about to ship

Before git commit, always:

git diff --staged --stat       # filenames + line counts
git diff --staged              # full content

If the diff includes anything you didn't intend, abort and unstage. Two minutes of verification beats two hours of "why is my commit also touching mind-maps.md?".

Rule 4 — Use a worktree for routine parallel work

When you know two sessions will be concurrent, give each their own working directory on the same branch:

cd C:\ssClawy\aguidetocloud-revamp
git worktree add ..\site-sessionB main

# Now session B works in C:\ssClawy\site-sessionB on the same main branch
# Each worktree has its own staging index — zero collision risk.

When session B is done:

git worktree remove ..\site-sessionB

The 2 May 2026 incident

This is why the rules exist.

Setup: - Session A: working on homepage + nav redesign. Many WIP files in static/css/style.css, layouts/partials/nav.html. - Session B: working on Mind Maps. WIP files in content/mind-maps/_index.md and static/js/mind-maps.js. - Both sessions on the same main branch in the same working directory.

What happened: 1. Session A finished its slice. Stashed changes with git stash push -m "wip". 2. Session A did git stash pop — this restored the changes, but ALSO left them staged in the index (stash pop's default). 3. Session A did git add layouts/partials/nav.html static/css/style.css — assuming this would only stage what they listed. 4. But the stash pop had already staged Session B's mind-maps.js and _index.md. git add <paths> doesn't unstage other files; it only adds to the index. 5. Session A did git diff --staged --stat — they saw 4 files instead of 2 but thought "oh, the stash pop must have grabbed extra". 6. Session A committed. Pushed. Cloudflare deployed. 7. Session B's incomplete Mind Maps code shipped to production.

Damage: 14 hours of broken Mind Maps page on production until Session B noticed.

Root cause: Not understanding that git stash pop stages everything it restores. Not catching the M indicator in git status -s.

Fix that's now baked in: Rules 1–4 above.

Reactive checklist when something already went wrong

If you discover a commit shipped files from another session:

  1. Don't git revert if the commit also contains your legitimate changes — you'll lose them.
  2. Use git revert --no-commit <sha>, then git restore --staged <files-to-keep>, then commit only the rollback portion.
  3. Or, if the wrong-files-shipped commit is the most recent: git reset --soft HEAD~1, then re-stage and re-commit only your intended files.
  4. Update Incident Log with the new pattern.

Bot-safe pushing

After your push, AI News / Roadmap / Service Health bots often try to push their scheduled updates. They use x-access-token:$TOKEN@github.com URLs and depend on the repo HEAD being where they last saw it.

If you've pushed ahead of them, they need git pull --rebase before their next push. The bots in susanthgit/-ainews, m365-roadmap, etc. have this baked in — but if you ever spin up a new bot, copy that pattern.

Cross-references