git-directory-management

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Git Directory Management

Git目录管理

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

当你在Git仓库中创建新目录时使用此技巧，尤其是在以下场景：

搭建项目结构
创建插件/包目录
将代码整理到新文件夹中
添加配置目录

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.

切勿在即将填充追踪文件的目录中创建
.gitkeep
文件。

.gitkeep

仅用于在版本控制中保留真正空的目录。

Pattern to Follow

遵循的模式

✅ DO - Add actual files directly

✅ 正确做法 - 直接添加实际文件

bash

undefined

bash

undefined

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


**关键点：**

- Git会在目录包含文件时自动追踪该目录
- 空目录创建与文件添加可一步完成
- 无需`.gitkeep`——实际文件会追踪目录

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

❌ 错误做法 - 先创建.gitkeep再立即添加文件

bash

undefined

bash

undefined

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

git add plugins/new-plugin/skills/ git commit -m "Add actual skill"


**错误原因：**

- 如果即将添加文件，`.gitkeep`毫无用处
- 会创建不必要的提交
- 用占位文件杂乱化目录
- 后续需要维护/删除多余文件

When to Use .gitkeep

何时使用.gitkeep

.gitkeep

is appropriate ONLY when:

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

Valid use case example:

bash

undefined

只有在以下情况才适合使用

.gitkeep

：

有效用例示例：

bash

undefined

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

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


**为何有效：**

- 应用启动前目录必须存在
- 目录会在运行时被填充（而非在版本控制中）
- `.gitkeep`确保空目录被追踪

Common Scenarios

常见场景

Scenario: Creating a new plugin structure

场景：创建新插件结构

✅ DO:

bash

mkdir -p plugins/new-plugin/{skills,commands}

✅ 正确做法：

bash

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:**

```bash
mkdir -p plugins/new-plugin/skills
touch plugins/new-plugin/skills/.gitkeep  # ❌ Wrong!

git add plugins/new-plugin/ git commit -m "feat: add new-plugin"


❌ **错误做法：**

```bash
mkdir -p plugins/new-plugin/skills
touch plugins/new-plugin/skills/.gitkeep  # ❌ Wrong!

Then add real files later

undefined

undefined

Scenario: Creating empty directories for runtime

场景：创建用于运行时的空目录

✅ DO:

bash

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.

✅ 正确做法：

bash

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

**为何正确：**缓存目录必须存在，但内容不会被追踪。

Scenario: Setting up tool configuration directories

场景：搭建工具配置目录

✅ DO:

bash

mkdir -p .config/tool

✅ 正确做法：

bash

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:**

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

git add .config/tool/config.json git commit -m "feat: add tool configuration"


❌ **错误做法：**

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

Decision Tree

决策树

text

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

text

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

避免不必要使用.gitkeep的好处：

更整洁的仓库（更少的占位文件）
更少的提交（一次提交包含实际内容）
后续无需清理（无需删除.gitkeep）
意图清晰（追踪文件表明目录用途）

不必要使用.gitkeep的问题：

用无意义的文件杂乱化目录
创建混乱的Git历史（空目录→填充内容）
最终需要清理
增加维护负担

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

经验法则：

即将添加文件？ → 无需
```
.gitkeep
```
目录保持为空？ → 使用
```
.gitkeep
```
还不确定？ → 等到文件存在后再提交

请记住：

Git通过目录中的文件来追踪目录
```
.gitkeep
```
用于真正空的目录
一次包含实际内容的提交胜过两次提交（空目录+填充内容）
如有疑问，先添加实际文件

Examples in This Repository

本仓库中的示例

Correct usage (runtime directories):

None currently - all directories contain tracked files

What NOT to do:

bash

undefined

正确用法（运行时目录）：

切勿这样做：

bash

undefined

❌ DON'T create .gitkeep in plugins/tools/skills/

This directory is meant to contain skills, not stay empty


**Correct approach:**

```bash


**正确做法：**

```bash

✅ 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"

undefined

git add plugins/tools/skills/new-skill/ git commit -m "feat(tools): add new-skill"

undefined