worktree-safety

Validate Git worktree and repository context before executing commands.

Updated Mar 24, 2026
One-click install
npx skills add https://github.com/yangshu2087/Codex --skill worktree-safety
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: worktree-safety
Source: https://github.com/yangshu2087/Codex/tree/main/.agents/skills/worktree-safety
Command: npx skills add https://github.com/yangshu2087/Codex --skill worktree-safety

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Safely operate in repositories that use Git worktrees or live inside a meta-workspace with multiple repos. This skill helps you avoid accidentally executing commands in the wrong repository by clearly identifying the active worktree and repository context, and by recognizing pointer directories and wrapper workspaces.

Core Features & Use Cases

  • Real repository detection: verify the top-level path and any worktree associations before executing commands.
  • Context validation: distinguish between normal repositories, pointer directories, and wrapper workspaces to avoid cross-repo side effects.
  • Safe operation guidance: provide checks and prompts to ensure the intended repository is targeted for branch or file operations.

Quick Start

Identify the real repository with git rev-parse --show-toplevel and validate any linked worktrees before executing git commands.

Frequently Asked Questions about worktree-safety

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I prevent executing Git commands in the wrong worktree?

Identify the real repository by verifying the top-level path with git rev-parse --show-toplevel and validating linked worktrees before executing commands to ensure operations target the correct worktree.

What is a Git pointer directory and how does it affect repository context?

A Git pointer directory is a wrapper workspace referencing multiple repositories rather than containing files directly. Distinguishing pointer directories prevents unintended cross-repo side effects during file manipulations.

How do I safely manage branch operations across multiple linked worktrees?

Safely manage branch operations across linked worktrees by applying context validation checks to distinguish normal repositories from wrapper workspaces, ensuring branch manipulations remain scoped to the intended repository.

Does this approach work for meta-workspaces containing multiple Git repositories?

Yes, this approach works for meta-workspaces by validating repository context before executing Git commands, recognizing wrapper workspaces, and preventing unintended changes in unrelated worktrees within the same directory.

Why are my Git file manipulations causing changes in an unrelated worktree?

Git file manipulations cause changes in unrelated worktrees when operating inside a meta-workspace without context validation. Distinguishing pointer directories and verifying the real repository prevents these cross-repo side effects.