Git Workflow

Use git switch for branch operations, never git checkout.

checkout is overloaded: checkout -- silently destroys uncommitted work, and checkout <branch> is ambiguous when a file shares the name. switch only switches branches. Use git restore for file-level operations.

Safety: never discard unowned work

The single most important rule: uncommitted work is the only work that can be lost — and multiple agents (Cursor, Codex, Claude) may share one working tree. A git stash, git reset --hard, git checkout -- . / git restore, or git clean -fd that "tidies up" silently wipes a concurrent session's uncommitted changes. This happened on 2026-06-15 — a git stash hid another agent's uncommitted ingests (Remix/Bit/theSVG), recovered only via the reflog, then committed.

• Commit your own work promptly (a WIP branch is fine) so a teardown can't lose it.
• Before any tree-clearing op, run git status; if there are changes you did not author, do not stash/reset/clean — commit to a branch or use a worktree.
• Parallel agents → separate git worktrees, never a shared checkout.
• Recover lost uncommitted work from git reflog (resets) or git stash list (stashes) — it is rarely truly gone.

Enforced for Cursor by the git-guard.sh beforeShellExecution hook (config/cursor/hooks/), which requires human approval before destructive git ops. Cross-agent rule: AGENTS.md § Git Safety.

Trunk-Based Development

The target is 200 lines of changed code or less per PR, excluding generated files. Larger changes get split into stacked diffs. Feature branches branch off dev. Keep features small and scoped.

Git Worktrees

Worktrees are the mechanism for managing multiple branches without context switching. Each worktree is a separate checkout of the same repository, with its own working directory and HEAD, sharing the underlying object database.

git fetch origin && git switch dev && git pull --ff-only
mkdir -p ../wt

git worktree add -b feat/a ../wt/a dev
git worktree add -b feat/b ../wt/b feat/a   # stacked
git worktree add -b feat/c ../wt/c feat/b   # stacked

After feat/a merges, rebase downstream:

git -C ../wt/b fetch origin && git -C ../wt/b rebase origin/dev
git -C ../wt/c fetch origin && git -C ../wt/c rebase feat/b

Use worktrees for: multiple independent features, stacked dependent changes, large refactors that need phasing, or parallel work that would cause file conflicts.

Conventional Commits

Format: type(scope): description. Type is feat, fix, refactor, docs, test, chore, or similar. Imperative mood, lowercase, no period, under 72 characters.

Never use "and" in a commit message. If you need "and", it is two commits.

Commit Hygiene

Before committing, run git status -sb and review diffs with git diff. Group changes by intent, not by file type. Use git add -p to stage precisely. If your branch is behind upstream, fetch and rebase before committing. When pushing after a rebase, use --force-with-lease instead of --force.

Branch Operations Without Stash

Never use git stash while other agents work in the same repository. The stash list belongs to the repository, so every worktree shares it, and a pop can apply another session's entry. A worktree of your own does not protect you. Source: Claude gt-cloud memory no-stash-in-worktrees.md, 2026-10-21

• Work on another branch in its own worktree: git worktree add ../wt/<name> <branch>.
• Set your own changes aside with a WIP commit on your branch: git commit -m "wip: <reason>" -- <paths>.
• Test a file against another revision without switching: git show origin/main:<path> > <path>, run the test, then git checkout HEAD -- <path>.

Join every step after a git switch with &&, never ;, and check git branch --show-current before you merge or commit. Source: Claude claude-of-tanks memory branch-switch-chain-trap.md, 2026-10-28

The other rules for shared checkouts are in private page.

Concept Position

Git at agent scale (OpenAI Pando)

OpenAI replaced its monorepo's Git backend with Pando to absorb agent traffic without changing how engineers or agents use Git. Pushes to different branches update in parallel; pushes to the same branch still apply in order. A fetch returns each branch tip's history, though two tips may reflect different moments. Pando answers fetches with links to stored packfiles that cover the gap, reusing them across many readers for CDN-like speed even if a pack holds objects the client already has. Push latency fell about 80%, and it serves nearly a petabyte of Git data a day. Source: X/@OpenAIDevs thread, 2026-11-03; Source: OpenAI, "Scaling Git at OpenAI"

The signal for small teams: agents multiply pushes and fetches, so Git throughput becomes infrastructure to plan for.

Parallel agents in worktrees hit the same wall: a fresh worktree has no node_modules or .env, and every one grabs port 3000 and the same dev database. workz gives each branch its own ports, database and dependencies in one command. Source: X/@rohansxd, 2026-07-16

---

Timeline

• 2026-10-30 | Replaced the stash-and-pop branch switch with worktrees, WIP commits and git show, because every worktree shares one stash list and a pop applied another session's stash. Source: Claude gt-cloud memory no-stash-in-worktrees.md, 2026-10-21
• 2026-07-01 | Concepts category refresh added this page to the Agent harness and runtime primitives family, linked it to Concept System Map, and kept it standalone because it owns this reusable mental model: Use git switch for branch operations, never git checkout. private page