agentsclimarketplace

Git worktree recovery

Skill Xopoko/plug-n-skills/plugins/git-worktree-safety/skills/git-worktree-recovery

Ready-to-install skills and plugins for Codex, Claude Code, and AI coding agents: practical workflows for app delivery, architecture, research, design, and agent tooling.

Install
npx -y skills add Xopoko/plug-n-skills --skill git-worktree-recovery

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 8 stars8 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Use when an expected Git worktree path or convenience symlink is missing, stale, or broken and a registered replacement may already hold the branch. Classifies branch-ref, reflog-only, object-only, or missing retention and guards POSIX-only exact symlink repair when directory-relative primitives are available. Do not use for Git administrative worktree repair after moving a main or linked worktree, ordinary worktree creation/removal/pruning, ref restoration, checkout/reset, stacked-change restacking, host-specific session orchestration, recovery of unsaved content from a vanished checkout, or arbitrary non-Git symlink repair.

SKILL.md

5.1 KB, as published. Nobody here has run it

Git Worktree Recovery

Recover the pointer only after proving that Git state is already safe. Resolve $PLUGIN_ROOT from the host's plugin-root variable when defined; otherwise use the absolute path of this skill folder's ../...

Read $PLUGIN_ROOT/skills/git-worktree-recovery/references/recovery-contract.md before interpreting salvage evidence or authorizing repair.

Safety Boundary

  • Start with audit; it is the default mode and performs only allowlisted read-only Git inspection.
  • Treat a live refs/heads/... ref containing every expected commit as repair authority. Reflog-only or object-only retention is salvage evidence, never authority to repoint a convenience link.
  • Require one unique registered replacement with the exact symbolic branch, HEAD equal to the live branch ref, a clean porcelain-v2 status including untracked files whose branch.oid and branch.head headers still equal that HEAD and requested short branch, no in-progress Git operation, and no locked or prunable annotation. Require at least one canonical full expected commit ID whose object type is directly commit.
  • Do not infer writer ownership from a worktree lock or a clean checkout.
  • Treat ref, reflog, and object evidence as committed-history evidence only. Uncommitted, untracked, or ignored content from a missing target cannot be proven or recovered; report that limit and never call pointer repair content recovery.
  • Repair only a verified broken symlink outside the common Git directory and every registered worktree, after explicit authorization. Never overwrite a regular file, directory, live symlink target, missing pointer, or link whose raw target changed after audit.
  • Never create, add, move, remove, prune, repair, unlock, or delete worktrees; restore or update refs; check out, reset, switch, rebase, or restack branches; recursively delete paths; or execute a shell.
  • Raw absolute paths remain present in command arguments and local filesystem access, but are omitted from JSON. The helper emits path digests, stable state codes, full object IDs, and bounded fingerprints instead.
  • Audit is host-neutral. Repair is limited to POSIX runtimes that feature-prove directory-relative no-follow inspection and atomic replacement; unsupported hosts remain read-only.

Workflow

  1. Read repository policy and identify a surviving checkout from the same repository, the full refs/heads/... ref, the registered replacement directory, the convenience link, and any full expected commit IDs.
  2. Run the read-only audit with the exact current raw link target and proposed new raw target. Relative symlink targets are resolved from the link parent.
  3. Accept ready only when authority is repoint and every Git, worktree, cleanliness, link, and target gate passes. salvage-only, blocked, or an evidence error is a stop condition.
  4. If pointer repair is authorized, pass the unchanged audit fingerprint to repair-link. The helper re-audits immediately, compares the fingerprint and raw target, replaces only the exact symlink, then proves relevant Git state remained unchanged.
  5. Re-run audit independently and report the final link state, branch/ref object ID, Git fingerprint, and any remaining stop condition.

Read-only audit:

python3 "$PLUGIN_ROOT/scripts/git_worktree_recovery_guard.py" \
  --repo /path/to/surviving-checkout \
  --branch-ref refs/heads/example-branch \
  --replacement /path/to/registered-replacement \
  --link /path/to/convenience-link \
  --expected-old-target ../missing-checkout \
  --new-target ../registered-replacement \
  --expected-commit 0123456789abcdef0123456789abcdef01234567

Separately authorized repair:

python3 "$PLUGIN_ROOT/scripts/git_worktree_recovery_guard.py" \
  --mode repair-link \
  --repo /path/to/surviving-checkout \
  --branch-ref refs/heads/example-branch \
  --replacement /path/to/registered-replacement \
  --link /path/to/convenience-link \
  --expected-old-target ../missing-checkout \
  --new-target ../registered-replacement \
  --expected-commit 0123456789abcdef0123456789abcdef01234567 \
  --expected-fingerprint AUDIT_FINGERPRINT \
  --apply

Exit 0 means ready, noop, or repaired; exit 2 is a safety refusal; exit 1 means malformed input or unavailable evidence. A successful repair is pointer-only proof, not permission for any later Git or delivery mutation.

Keep looking

Skills are one crate of 328,083. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.