sparse-checkout

name

sparse-checkout

description

Personally hide files or directories from a git repo's working tree via git sparse-checkout — no .gitignore changes, invisible to teammates. Use whenever the user wants to ignore team-committed paths just for themselves (e.g. .claude/, dist/, generated docs), restore a hidden path, list what's hidden, or undo all hiding. Triggers on "hide X locally", "ignore X locally", "make git stop showing X", "restore hidden files", "what did I hide". Distinct from .gitignore (committed, team-wide) — this is per-clone, reversible, stays private.

sparse-checkout

Locally hide files and directories that teammates committed, without modifying any tracked file. The exclusion lives in .git/info/sparse-checkout, which is per-clone state — your teammates never see it, and git push cannot carry it.

When to use

• Teammates committed personal config / generated output that you don't want in your tree (e.g. .claude/, dist/, vendor/)
• You want a private exclusion without proposing a .gitignore change to the team
• The user asks to restore a previously hidden path, or to see what's currently hidden
• The user wants to undo all local hiding

Mental model

Behind the scenes this uses git sparse-checkout in non-cone mode, which accepts gitignore-style patterns. A typical patterns file looks like:

/*
!.claude/
!docs/private/

Read as: "include everything at the root, except .claude/ and docs/private/." The patterns file is .git/info/sparse-checkout; it lives inside .git/, so it's never pushed and never affects anyone else.

git sparse-checkout disable blows the whole thing away and the clone behaves like a normal one again.

Operations

Use the helper script scripts/sparse_checkout.py (relative to this SKILL.md). Resolve its absolute path and run it from anywhere inside the target repo — the script discovers the repo root itself, and path arguments are interpreted relative to that root (not your cwd).

Goal	Command
Hide one or more paths	python <skill-dir>/scripts/sparse_checkout.py hide <path> [path...]
Restore one or more paths	python <skill-dir>/scripts/sparse_checkout.py restore <path> [path...]
List what's hidden in this repo	python <skill-dir>/scripts/sparse_checkout.py list
Show status (enabled? what's hidden?)	python <skill-dir>/scripts/sparse_checkout.py status
Disable entirely (bring all files back)	python <skill-dir>/scripts/sparse_checkout.py disable

The script auto-detects whether a path is a directory and appends a trailing / so the pattern unambiguously matches the whole subtree.

Safety checks — perform these BEFORE running hide

Sparse-checkout removes tracked files in the excluded paths from the working tree, but leaves untracked files alone. Both behaviors can surprise users. Walk through this checklist:

1. Check for uncommitted modifications under the target path. Run git status --short -- <path>. If anything tracked shows up (M / A / D / R), stop and report — the script enforces this and will refuse the hide. (Background: git sparse-checkout reapply is permissive and would warn-but-succeed, leaving the dirty files on disk while the patterns file commits to hiding them — a silent half-applied state that risks losing the modifications on the next checkout. So the script does a hard pre-flight check.) Ask the user whether to commit, stash, or skip.

2. Note untracked personal files under the target path. Run git ls-files --others --exclude-standard -- <path>. If anything is listed, warn the user: those files stay on disk after hiding, so the directory won't fully disappear — it will contain only their personal junk. Usually fine, but they may want to move that content out first.

3. Confirm it's a git repo. The script bails with a clear error if not, but it's nicer to know upfront.

For restore, no special checks are needed — restored content comes from the git index and is canonical.

Workflow

When the user asks to hide something:

1. Identify the target path(s). If ambiguous (e.g. "hide the claude stuff"), confirm the exact path.
2. Run the safety checks above and report any findings.
3. Run the hide command.
4. Confirm with the user by reading back the resulting state (the script prints it automatically).
5. Mention the inverse command they can use to undo (restore <path> or disable).

When the user asks to restore or undo:

1. Run list first if the path isn't clear, so you can show them options.
2. Run restore <path> (specific) or disable (everything).
3. Confirm the new state.

Example interactions

Example 1 — hide a noisy directory

User: "hide .claude/, teammates keep committing stuff into it"

1. Run git status --short -- .claude/ and git ls-files --others --exclude-standard -- .claude/ to check the state.
2. Report findings — e.g. "you have 2 untracked files under .claude/ (agents/my-foo.md, settings.local.json). They'll stay on disk after hiding; the directory will only contain those. Proceed?"
3. After confirmation, run python <skill-dir>/scripts/sparse_checkout.py hide .claude/.
4. Echo the resulting hidden list.
5. Mention restore .claude/ undoes it.

Example 2 — list and partial restore

User: "I hid a few directories before — list them, then restore the docs one"

1. Run ... list to show what's hidden.
2. From the list pick the docs/* entry the user means; if multiple, ask which.
3. Run ... restore docs/internal/ (or whichever).
4. Echo the new state.

Example 3 — full undo

User: "restore everything, I don't want sparse-checkout anymore"

1. Run ... disable.
2. Confirm it's off; all files are back.

Edge cases

• Sparse-checkout already initialized: the script reads the existing pattern file and merges new exclusions without duplicating.
• Hiding a path that's already hidden: no-op, the script reports (already hidden: <path>).
• Restoring a path that wasn't hidden: no-op, reports (not hidden: <path>).
• Restoring the last remaining exclusion: the script runs git sparse-checkout disable for a clean state instead of leaving a no-op patterns file.
• Not a git repo: the script exits with a clear error; surface it to the user.
• Path doesn't exist in HEAD: still allow hiding — it may exist in other branches the user will check out later.

What not to do

• Don't edit .git/info/sparse-checkout by hand from the model. Use the script — it writes the patterns file and calls git sparse-checkout reapply, with a rollback on failure so the patterns file never diverges from the actual working tree.
• Don't propose adding the path to .gitignore instead. That's a different problem (preventing new commits of the path) and affects the whole team. This skill is for the opposite case: the path is already tracked, and you personally don't want it in your tree.
• Don't use this in CI / shared scripts. It's a developer-machine convenience.