git-sync
Use whenever doing git branch work — starting a task, committing, pushing, rebasing, amending, opening a PR, or cleaning up after a merge. Keeps local and origin in sync: work always on a dedicated br
SKILL.mdskills/git-sync/SKILL.md
GitHubGit Sync
Goal: keep git from getting tangled. Local and origin stay in lockstep, history stays linear, and the working branch is always rebased on top of current main (and any branch it depends on). Apply this on any branch work.
Who writes the code: if implementation is delegated to another agent, git operations themselves stay with the orchestrating agent: branching, rebasing, committing, pushing, PRs, and merges are its job, and no worker or delegate ever commits. The delegate produces the diff; the orchestrator lands it. (Who executes in this install:
LOCAL.mdbeside this skill, when your copy keeps one — Who writes the code.)
Exclusion: worktree-agent-* branches (temporary branches for isolated
worktree agents). Do NOT apply the sync workflow to them — no rebasing, no
pushing; they die with their worktree. They DO get pruned once orphaned: never
pushed means never : gone], so only the "merged local-only" prune in the sweep
below catches them. Don't touch one whose worktree is still live (-d refuses
anyway — that's the guard).
Defaults chosen by the user (apply automatically, no pausing):
- Fully autonomous for rebase, force-push, and pruning merged local branches.
- Force-push uses
--force-with-lease— never bare--force. - Rebase cadence: onto fresh main when starting work on a branch, and again right before any push or PR.
- Main is updated fetch-only — never checked out (a shared working tree; checking out main yanks it from concurrent sessions).
Hard gates (check before the first mutation, every session)
Never commit on
mainor a shared branch. Before any code change, create your own dedicated branch — a commit on main in a shared checkout is immediately visible to (and rebased under) every other session. If you find yourself on main with edits:git switch -c <branch>first, then commit.In a SHARED working tree, isolate in a worktree. A main checkout used by concurrent sessions or agents can have its branch switched under you mid-task — committing there risks landing your work on someone else's branch. Do code work in a dedicated worktree on your own branch. If the project ships a one-shot worktree command, prefer it; it usually also copies the untracked env/config files a fresh worktree lacks. Manual equivalent:
git worktree add -b <branch> ../<repo>-<slug> main cd ../<repo>-<slug> cp ../<repo>/.envrc . && direnv allow # untracked env files do not come along cp ../<repo>/<untracked-local-config> <same-path> # any gitignored config the app needs pnpm install # a fresh worktree has NO node_modulesThe project's own one-shot command and its config-copy step:
LOCAL.mdbeside this skill, when your copy keeps one — Creating a worktree.No AI attribution in commits or PRs. Never append an AI-generated attribution line or AI
Co-Authored-Bytrailer to commit messages or PR bodies — the user's standing rule, every project. Substantive content only.A PR isn't "up" until it's green. After opening or pushing to a PR, poll the checks (
gh pr checks <n> --watch) and only report/hand off the PR when all pass. A failure means fix and re-push, not announce. Caveat: in a repo whose CI path-filters them out, docs-only PRs (e.g.plans/**) trigger ZERO checks — "no checks reported" +gh pr view <n> --json mergeable,mergeStateStatusshowing MERGEABLE/CLEAN counts as green; don't wait on a suite that will never start. (Which repos behave this way here:LOCAL.mdbeside this skill, when your copy keeps one — Docs-only PRs trigger no checks.)
Working inside a worktree
Creating the worktree is the easy half. Almost every recorded incident happened while operating in one — because cwd, branch, and the worktree's continued existence are all assumptions that quietly fail.
- Never rely on cwd when more than one worktree exists — pass
git -C <abs-path>explicitly, every time. The harness resets cwd between calls, so acdin one call does not hold for the next: agit branch --show-current"confirming" the branch was reporting a different checkout, and acd <main-checkout> && git rebase origin/mainmeant to rebase a feature branch rebased main instead (harmless only by luck). Nevercdinto the shared main checkout to run branch operations. - Target the worktree's absolute path when editing, too — edits and commits
aimed at main-checkout paths land on
main, not your branch. - Re-check the branch before any mutation (
git rev-parse --abbrev-ref HEAD). A worktree's branch can be silently flipped at session start, and a concurrent session can switch it under you mid-task. - A successor session taking your branch leaves YOUR worktree DETACHED. A
branch can be checked out in only one worktree, so the handover detaches yours —
and
git status --shortreports clean, so nothing looks wrong. Checkgit branch --show-current(orgit status -sb) in the sweep: "clean" and "on the right branch" are different claims. The work survives only because it was pushed — push before handing a branch to another session. - Your worktree may not survive the session. It can be deleted externally
mid-session, or claimed by a session you just spawned. Run
git worktree listbefore any sweep and treat any worktree you did not just create as occupied. - A worktree whose
node_modulesis a symlink to the main checkout blockspnpm add— install from the root, or give the worktree its own install.
The invariants
main is always current — update it without leaving your branch:
git fetch origin main:mainThis fast-forwards the local
mainref toorigin/mainwithout checkout. (If it errors — not fast-forwardable, orrefusing to fetch into branch 'main' checked out at <path>because a concurrent worktree holds main — justgit fetch originand rebase ontoorigin/maininstead. Never force local main.)The working branch is rebased onto latest main — at task start and before every push/PR:
git fetch origin main:main git rebase mainBranches that depend on another branch rebase onto that branch, not main. Fetch the dependency first, then
git rebase <dependency-branch>. When the dependency later merges to main, rebase back onto main and drop the dep — mechanics in restacking-and-stacks.md.Branches stay pushed. After committing, push. First push of a new branch:
git push -u origin <branch>.Any history rewrite is force-pushed — keep origin identical to local. After every rebase, amend, squash, or reword:
git push --force-with-lease origin <branch>--force-with-lease, never--force: it refuses if origin moved underneath you (a concurrent session), surfacing the conflict instead of clobbering it.Prune local branches whose remote is gone. Remotes are deleted on PR merge, so a missing upstream means merged-and-done:
git fetch --prune git branch -vv | grep ': gone]' → git branch -D <branch>Only delete a branch you are not currently on; switch away first if needed.
Procedure at a glance
Starting work on a branch:
git rev-parse --abbrev-ref HEAD # confirm which branch you're on (gate 1)
git fetch origin main:main # refresh main (no checkout)
git rebase main # (or rebase onto the dependency branch)
git push --force-with-lease origin HEAD # only if the rebase moved commits
Before any push or PR:
git fetch origin main:main
git rebase main
# resolve conflicts if any, then:
git push --force-with-lease origin HEAD # plain push if no rewrite happened
When a base branch was amended/rebased/squash-merged, or you're running a multi-PR stack: read restacking-and-stacks.md first — a plain rebase in those situations duplicates commits or conflicts against rewritten twins.
After a PR merges (cleanup) — remove the WORKTREE too, not just the branch. A merged PR's worktree is dead weight; leaving it is how orphaned worktrees pile up. Clean as you go, the same session the PR merges:
git fetch --prune
git worktree remove <path-of-the-merged-branch's-worktree> # if it had one; plain remove refuses if dirty
git branch -vv | grep ': gone]' # branches whose remote was deleted
git branch -D <those branches> # also delete branches merged via squash/rebase (no ': gone')
git worktree prune # drop admin refs for already-removed dirs
Worktree removal deletes a full node_modules (~30-60s on a 5.5k-file repo) — run
a multi-worktree removal in the background (see LEARNINGS.md beside this skill,
when your copy keeps one). Re-check git status --porcelain right before each
removal and let plain git worktree remove (never --force on unseen state)
refuse a dirty tree.
The PR body
Every PR description has the same three parts, in this order:
- Summary — the smallest visual that makes the change clear. Pseudocode of the new flow, a call tree, a file-tree diff, a before/after table, or a mermaid diagram; prose only for what the visual cannot carry. One or two sentences of why, and the ticket link.
- Evidence — before and after. A screenshot or recording for UI; otherwise the exact command whose output was red before and green now (name the regression test). Every claim in the body is one you checked: colleagues read it as fact.
- Merge danger. Two lines:
Door: one-way | two-wayandBlast radius: <one word>(none, module, service, data, users). Two-way means a plain revert fully undoes it. A one-way call names the checked fact that makes it so — a destructive migration, a published contract, a message sent, a branch that deploys on merge — and a one-way door gets an independent second review before merge.
Nothing else is required, and an AI attribution line is never allowed (hard gate 3).
<!-- PR body shape adapted from mattpocock/skills `pr` (MIT, (c) 2026 Matt Pocock). -->End-of-work / handoff / archive sweep (MANDATORY)
Cleanup is not "on request" — accumulation (dozens of : gone] branches, orphaned
worktrees) is the failure this skill exists to prevent. Run this sweep at the end
of a task, at every handoff, and before archive_session. Two tiers:
Auto-prune the provably-safe set (no confirmation). Two categories of dead branch — both must be swept, because they accumulate through different holes:
git fetch --prune
# (a) UPSTREAM-GONE: branches whose remote was deleted on merge. EXCEPT the
# checked-out branch (branch -D refuses branches held by a worktree — the guard).
git for-each-ref --format='%(refname:short) %(upstream:track)' refs/heads \
| awk '$2=="[gone]"{print $1}' | grep -v '^worktree-agent-' \
| while read -r b; do git branch -D "$b"; done
# (b) MERGED LOCAL-ONLY: branches with NO upstream that are fully merged into
# origin/main — never-pushed feature branches AND orphaned worktree-agent-*
# whose worktree was removed. --merged origin/main proves zero unmerged commits;
# -d (not -D) double-checks and refuses anything not merged; a branch a live
# worktree still holds is refused too. Both are the safety net, so this can't
# eat unpushed work (an unpushed plan branch has commits ahead of main → excluded).
git branch --merged origin/main --format='%(refname:short) %(upstream)' \
| awk '$1=="main"{next} $2==""{print $1}' \
| while read -r b; do git branch -d "$b"; done
# remove CLEAN worktrees whose branch is merged (background; plain remove)
git worktree prune
Category (b) is the hole that let a pile of merged worktree-agent-* branches
survive: local-only (never pushed → never : gone]), and the old sweep skipped
them by name. --merged origin/main + -d makes deleting them provably safe.
Sweep sessions too, not just branches. When the session-mesh tools are
available (ccd_session_mgmt), a merged PR usually has a session that owned it:
list_sessions locates it by title/branch, archive_session retires it. Offer
the archive (report, don't silently archive) — a session that looks done may
still be holding follow-up state.
Report, never auto-delete, the ambiguous set — surface these for a human:
- Dirty worktrees (uncommitted changes) — could be another session mid-flight.
- Local-only branches with no upstream — verify merged first (
git rev-list --count origin/main..<branch>== 0 means fully merged → safe; otherwise it holds unpushed work — flag, don't delete). - Branches with a live remote (e.g. a shared
prod-hot-fix) and known-KEEP branches (unpushed plans, re-land-pending rescue branches).
Automated backstop. Run the same sweep unattended: a session-end hook and a
weekly scheduled job (a launchd agent, cron, or similar) should both call one
shared implementation — a sweep script over a list of repos. It is a plain shell
job — the decision procedure is fully deterministic, so it needs no model in the
loop and costs no tokens. Make dry-run the default so anyone can see exactly what
it would do, any time, and require an explicit --apply to act; have the
scheduled run append to a log you can tail. (This install's hook and script paths,
launchd label, repo list and log: LOCAL.md beside this skill, when your copy
keeps one — Automated sweep backstop.)
# shape of the interface — dry-run is the default
bash <path>/sweep-worktrees.sh
bash <path>/sweep-worktrees.sh --apply # act
tail -40 <log-dir>/sweep-worktrees.log # what the weekly run did
🔑 Why the old hook's "never remove a worktree" exemption was the bug, not the
safety feature it looked like. A worktree PINS its branch — git branch -D
refuses a branch checked out anywhere — so declining to remove worktrees made
the branch prune a no-op for exactly the branches that mattered. One audit found
45 worktrees / 65 branches / ~12 GB across three repos, all downstream of that
one exemption. The same hook also hardcoded origin/main,
which silently disabled clause (b) in every develop-based repo. The sweep now
derives the base from origin/HEAD.
A worktree is removed only if EVERY gate passes; any gate that cannot be
evaluated resolves to KEEP: not the main checkout · not --excluded · clean
tree · no session transcript touched within --idle-hours (24h default, read
from ~/.claude/projects/<slug>/*.jsonl mtime) · branch is [gone] or 0 ahead
of base · no open PR · tip older than --min-age-days. Branches checked out in
any worktree, and branches matching the protected pattern (main|master|develop| release|staging*|production*, overridable via a protected-list file beside the
script — this install's path is in LOCAL.md beside this skill, when your copy
keeps one), are never candidates.
⚠️ gh failure must not mean "assume a PR exists." The first draft failed
safe that way and was therefore a silent no-op for any repo without a GitHub
remote — and for every run where gh was offline or unauthenticated. The sweep
now probes gh repo view once per repo: when gh can answer, the per-branch PR
check is authoritative; when it cannot, the PR gate is dropped and branch state
alone decides, which is already decisive (0-ahead means there are no unique
commits to lose). A fail-safe that disables the entire job is not a safe default.
Safety rules / failure modes to catch yourself on
- About to run a git mutation without checking the branch? Stop —
git rev-parse --abbrev-ref HEADfirst. In a shared tree a concurrent session may have switched it under you. - Never force-push main or any shared/protected branch. Force-push applies only to your own feature branch.
--force-with-leaserejection is a signal, not a nuisance. Origin advanced under you — fetch, inspect, reconcile (rebase your work on top), then retry. Do not escalate to--force.- Linear history only. Integrate with rebase, never merge commits. Don't create merge commits to "catch up" a branch — rebase it.
- Rebase conflicts: resolve,
git rebase --continue. If it goes sideways,git rebase --abortreturns you to safety; reassess before retrying. - Don't delete unmerged work. Prune only branches proven merged (
: gone], or--merged origin/main). Agonebranch with unpushed local commits you don't recognize → stop and flag it rather than-D. - "Committed, not pushed" in a handoff note = a commit at GC risk. At resume,
git branch -a --contains <sha>; if nothing contains it, pin it immediately (git branch rescue/<topic>-<sha7> <sha>) before analyzing (seeLEARNINGS.mdbeside this skill, when your copy keeps one).
Commands that destroy uncommitted work
Three separate incidents, one shape: a git command doing exactly what it documents while the caller expected an "undo".
git checkout -- <file>is not "undo my last edit". It restores from HEAD/index, so using it to revert a temporary edit (a mutation, a debug print) on a file whose real work is uncommitted discards the entire slice in that file. It presented as a legitimate test failure — the specs were untouched, so the suite went red — and cost a full re-implementation. To undo a temporary edit,cpthe file aside andcpit back. Detection: after restoring,git statusshould STILL list the file as modified; if it went clean, you just deleted your work. Structural fix: commit the slice before mutation-testing it, then amend.git reset --hard origin/mainassumes a clean tree. The common slice cadence (fetch && reset --hard→ commit on top) destroyed a finished, unpushed edit — same family as above with a wider blast radius:checkouttakes one file,reset --hardtakes the tree. Commit or stash first.- Never chain a push onto a rebase. A conflicted rebase stops with HEAD
detached while the branch ref still points at the pre-rebase commit — and a
pipe between the two commands swallowed the exit status
&&relied on, so the push ran and published the stale commit as a clean-looking* [new branch]. Rebase, verify, then push, as separate steps. Before any push, check for an in-progress rebase:ls -d "$(git rev-parse --git-path rebase-merge)" 2>/dev/null(plain.git/rebase-mergedoes not work in a worktree), and treat a literalHEADfromrev-parse --abbrev-refas detached ⇒ do not push. - Stage explicit paths, never
git add -A. Apnpm install --ignore-workspacefabricated a nested lockfile and workspace file (~3.4k untracked, non-ignored lines) thatgit add -Astaged without complaint, silently decoupling the package from the root workspace. Before committing, diff the staged list against the slice's intent (git diff --cached --name-only | grep -E 'lock|workspace|\.claude');git ls-tree origin/main <path>answers "did my tooling create this?"
In a rebase-merge repo, prove merged-ness by CONTENT, not ancestry
Rebase-merging rewrites every commit hash, so a merged branch's local tip and main's copy are different objects with identical trees. Consequently:
git merge-base --is-ancestorsays NO for branches that are fully merged, andgit branch --merged origin/mainwon't list them. Don't panic, and don't prune on that signal. Prove disposability withgit diff <tip> origin/mainbeing empty.git branch -dsucceeding is a weaker guarantee than it looks — it means merged into its upstream, not into main. Verify, then delete.- A commit written AFTER the PR merged does not reach main. It sits on the branch
until some later PR carries it — check
git show origin/main:<file>rather than assuming a push landed it. A quietgit push -qwith tailed output hides this. - Syncing after a rebase-merge:
git diff origin/main --statempty proves your work is fully upstream, makingreset --hard origin/main+push --force-with-leaselossless — and gives the safety classifier the specific justification it demands.
PR mechanics that mislead
gh pr mergefrom inside a worktree printsfatal: 'main' is already used by worktree at …— the MERGE still succeeded. But verify both halves independently:gh pr view <n> --json statefor the merge, andgit ls-remote --exit-code --heads origin <branch>for the branch. ⚠️ gh's cleanup appears to abort as a unit, so--delete-branchmay leave the remote branch alive — an earlier note claiming the remote delete still succeeds was wrong. Expect the manualgit push origin --deleteto be blocked by the safety classifier (merging a PR is not the user naming a branch deletion); that is correct — leave it, record a follow-up, and sweep merged branches in one authorized batch.- Never use
gh pr merge --autoon a repo without required status checks — it waits for nothing and merges instantly, silently bypassing merge-on-green. Rungh pr checks --watchto green, then merge explicitly. (A GraphQL "unstable status" error on the first attempt just means checks were still registering.) - When GitHub and a local dry-run disagree about conflicts, suspect a custom merge
driver.
.gitattributesdeclaring**/LEARNINGS.md merge=unionis honored by local git and ignored by GitHub's server-side merge, so concurrent journal appends show as CONFLICTING whilegit merge-treereports clean. Resolve locally — rebase onto main (union applies during replay),push --force-with-lease, then merge. Never resolve in the GitHub UI. - A CONFLICTING PR gets NO CI runs, which presents as "no checks reported" and is
easily mistaken for a docs-only PR. After every rebase-merge,
git fetch && git rebase origin/mainbefore opening a follow-up PR from the same branch — duplicates drop automatically. - A rebase-merged PR's green CI can hide a lockfile broken by a sibling merge.
PR CI never re-runs post-rebase, so main can look green while every
pnpm install --frozen-lockfilefails. When a lockfile-adjacent PR rebase-merges after any sibling that regenerated the lockfile, verify main immediately. Diagnosis handle: tag builds all failing in ~30s at "install dependencies" = lockfile drift on main, not a code problem.
Before you call this done
- You are on your own dedicated branch (never main), in a worktree if the checkout is shared.
- The branch is rebased onto current main (or its dependency) and pushed; origin matches local after any rewrite.
- Commits are atomic, messages substantive, no AI attribution trailers.
- Any PR you opened/pushed is green (or provably has no checks) before you report it.
- The end-of-work sweep ran: safe set pruned, ambiguous set reported, merged worktrees removed.
Capturing learnings (session-handoff protocol)
Append durable git workflow gotchas to LEARNINGS.md beside this skill, when your
copy keeps one — gh/CLI
failure modes, prune holes discovered, re-stacking traps — deduped and tagged
by repo. Read it before non-trivial git surgery (stacks, bulk prunes, recovery).