mac-apfs-case-insensitive-git-tracking

What problem does it solve?

This Skill addresses confusing case mismatch issues that arise when developing on macOS's default case-insensitive APFS filesystem, where git tracks files under their originally committed case (often lowercase) even when you write to a path with different casing (like docs/API.md instead of the tracked docs/api.md). This is especially problematic for cross-platform projects using Linux Docker containers or CI/CD pipelines, where case-sensitive filesystems can cause build failures or file not found errors.

Core Features & Use Cases

• Non-destructive diagnostics: Provides step-by-step checks to confirm if a file write succeeded by verifying git tracked case, filesystem inode equivalence, and diff content without making harmful changes.
• Mistake prevention: Explicitly warns against ad-hoc case-only git renames that break git history and cause compatibility issues on Linux hosts.
• Prevention conventions: Defines best practices to avoid case mismatch traps, such as matching tracked case in patch paths and verifying writes via inode checks.
• Use case: Ideal for developers working on monorepos with uppercase documentation files (API.md, PRD.md etc.) who see unexpected lowercase paths in git status after successful write operations, or who encounter case-related build failures in Docker/CI environments.

Quick Start

Use the mac-apfs-case-insensitive-git-tracking skill to diagnose why your recent write to docs/API.md is showing as modified api.md in git status and confirm if the change was applied correctly without making any harmful file renames.