git-troubleshooting

Diagnose Git command failures involving tracked, ignored, and untracked files.

1|Updated Mar 18, 2024

Search Tags:#git #debugging #troubleshooting #worktree #detached head #gitignore #pathspec

Ready to run

npx skills add https://github.com/erfianugrah/dotfiles --skill git-troubleshooting-erfianugrah

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: git-troubleshooting
Source: https://github.com/erfianugrah/dotfiles/tree/main/.pi/agent/skills/git-troubleshooting
Command: npx skills add https://github.com/erfianugrah/dotfiles --skill git-troubleshooting-erfianugrah

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill helps you diagnose and resolve common Git command failures where operations behave as if files are missing, including git mv/add/rm/checkout errors and misleading status behavior.

Core Features & Use Cases

Diagnostic battery: Runs a focused sequence to identify wrong cwd, repository root, tracked vs ignored vs untracked status, and recent history for a path.
Symptom → cause mapping: Converts frequent error messages into first hypotheses and targeted probes, with emphasis on gitignore and working directory mistakes.
Practical rescue guidance: Covers detached-HEAD recovery, dirty-tree checkout blocking, and safe “when to give up” cleanup steps.

Quick Start

Run the git-troubleshooting diagnostic on the failing path X by executing the full battery (pwd, git rev-parse, git status -uall, git ls-files, git check-ignore -v, optional .gitignore view, and recent git log for the path) in a single bash call.

Frequently Asked Questions about git-troubleshooting

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

FAQPage Schema

Why does git mv say a file is not under version control when I can see it in my directory?▼

Git mv fails with this error when the target file is untracked or ignored. Running a diagnostic battery using git ls-files and git check-ignore -v verifies the file's tracked status and ignore rule provenance to pinpoint the mismatch.

How do I fix pathspec errors during git add or git checkout?▼

Pathspec errors occur when Git cannot match your file path against tracked or untracked entries. Validate your repository root with git rev-parse and enumerate exact paths using git status -uall to resolve the working directory mismatch.

Why are files missing from git status even though they exist in my worktree?▼

Files missing from git status are frequently trapped by gitignore rules. Execute git check-ignore -v to trace the specific ignore rule and its provenance, confirming whether the path was ever tracked in recent history.

How do I recover a detached HEAD state in my local worktree?▼

Recover a detached HEAD by checking recent history with git log to find your previous branch commit. Practical rescue guidance helps you re-attach the HEAD pointer safely without losing uncommitted worktree changes.

What is the best way to troubleshoot a dirty tree blocking my git checkout?▼

Troubleshoot a dirty tree checkout block by running a focused diagnostic sequence to enumerate status and tracked paths. This identifies untracked overwrites, allowing you to safely clean or stash files before retrying the checkout.

How do I diagnose git command failures when file operations behave as if files are missing?▼

Diagnose missing file behavior by executing a full diagnostic battery in a single call. Validate the cwd, enumerate untracked files with git status -uall, and check recent history to confirm if the path was ever tracked.