git-directory-management

name	git-directory-management
description	Manage git-tracked directories correctly - never create .gitkeep files in directories that will immediately contain tracked files

Git Directory Management

When to Use This Skill

Use this skill when creating new directories in a git repository, especially when:

• Setting up project structure
• Creating plugin/package directories
• Organizing code into new folders
• Adding configuration directories

Core Principle

Never create .gitkeep files in directories you're about to populate with tracked files.

.gitkeep is ONLY for keeping truly empty directories in version control.

Pattern to Follow

✅ DO - Add actual files directly

# Create directory and add actual file
mkdir -p plugins/new-plugin/skills
# Now add your actual files
# (Write SKILL.md, plugin.json, etc.)

Key points:

• Git automatically tracks directories when they contain files
• Empty directory + file creation can happen in one step
• No .gitkeep needed - the real files track the directory

❌ DON'T - Create .gitkeep then immediately add files

# This is wasteful and wrong
mkdir -p plugins/new-plugin/skills
touch plugins/new-plugin/skills/.gitkeep  # ❌ Unnecessary!
git add plugins/new-plugin/skills/.gitkeep
git commit -m "Add empty directory"

# Then immediately add real files
# (Write SKILL.md)
git add plugins/new-plugin/skills/
git commit -m "Add actual skill"

Why this is wrong:

• .gitkeep serves no purpose if files are coming
• Creates unnecessary commits
• Clutters directory with placeholder file
• Extra file to maintain/remove later

When to Use .gitkeep

.gitkeep is appropriate ONLY when:

1. The directory must exist but remain empty
2. The empty directory is required for the application to function
3. No files will be added to the directory immediately

Valid use case example:

# Application requires logs/ directory to exist on startup
mkdir -p logs
touch logs/.gitkeep
git add logs/.gitkeep
git commit -m "chore: add logs directory for runtime output"

Why this is valid:

• Directory must exist before application runs
• Directory will be populated at runtime (not in version control)
• .gitkeep ensures the empty directory is tracked

Common Scenarios

Scenario: Creating a new plugin structure

✅ DO:

mkdir -p plugins/new-plugin/{skills,commands}
# Then immediately create your files:
# Write plugins/new-plugin/.claude-plugin/plugin.json
# Write plugins/new-plugin/skills/skill-name/SKILL.md
# Write plugins/new-plugin/README.md
# Add all files in one commit
git add plugins/new-plugin/
git commit -m "feat: add new-plugin"

❌ DON'T:

mkdir -p plugins/new-plugin/skills
touch plugins/new-plugin/skills/.gitkeep  # ❌ Wrong!
# Then add real files later

Scenario: Creating empty directories for runtime

✅ DO:

mkdir -p tmp/cache
touch tmp/cache/.gitkeep
git add tmp/cache/.gitkeep
git commit -m "chore: add cache directory for runtime"

Why this is correct: Cache directory must exist but contents are not tracked.

Scenario: Setting up tool configuration directories

✅ DO:

mkdir -p .config/tool
# Immediately add configuration file
# Write .config/tool/config.json
git add .config/tool/config.json
git commit -m "feat: add tool configuration"

❌ DON'T:

mkdir -p .config/tool
touch .config/tool/.gitkeep  # ❌ Wrong! You're about to add config.json

Decision Tree

Creating a new directory?
│
├─ Will you add tracked files immediately?
│  └─ YES → No .gitkeep needed, just add the files
│
└─ Will the directory stay empty in version control?
   │
   ├─ YES, and it must exist → Use .gitkeep
   │
   └─ NO, files coming later → Wait until files exist, then commit

Why It Matters

Benefits of not using .gitkeep unnecessarily:

• Cleaner repository (fewer placeholder files)
• Fewer commits (one commit with actual content)
• No cleanup needed later (no .gitkeep to remove)
• Clear intent (tracked files show directory purpose)

Problems with unnecessary .gitkeep:

• Clutters directories with meaningless files
• Creates confusing git history (empty → populated)
• Requires eventual cleanup
• Adds maintenance burden

Quick Reference

Rule of thumb:

• About to add files? → No .gitkeep
• Directory stays empty? → Use .gitkeep
• Not sure yet? → Wait until files exist

Remember:

• Git tracks directories through their files
• .gitkeep is for truly empty directories
• One commit with actual content beats two commits (empty + populated)
• When in doubt, add the real files first

Examples in This Repository

Correct usage (runtime directories):

• None currently - all directories contain tracked files

What NOT to do:

# ❌ DON'T create .gitkeep in plugins/tools/skills/
# This directory is meant to contain skills, not stay empty

Correct approach:

# ✅ Just add your skill directly
# Write plugins/tools/skills/new-skill/SKILL.md
git add plugins/tools/skills/new-skill/
git commit -m "feat(tools): add new-skill"