Quick Start
Get Started in 5 Minutes
# 1. 验证 main 分支干净
git log main -- docs/ # 应返回空
# 2. 创建孤立 docs 分支
git checkout --orphan docs
git rm -rf .
mkdir docs && echo "# Dev Guide" > docs/guide.md
git add docs/ && git commit -m "chore(docs): init"
# 3. 回到 main，开始使用
git checkout main
Daily Use (Every Development Session)
# 获取文档进行开发
git checkout -b feat-xxx
git archive docs docs/ | tar -x -C .
echo "docs/" >> .git/info/exclude
# 开发完成后
git add src/ && git commit -m "feat: xxx"
git checkout main && git merge feat-xxx
rm -rf docs/
Task Objectives
- This Skill is used to: manage local development documentation, ensuring the docs/ directory never enters the Git history of the main branch
- Capabilities include: creating orphan documentation branches, securely extracting documentation, branch merge protection, documentation isolation verification
- Trigger conditions: used when the user needs to maintain development documentation locally but does not want to commit it to the main branch
Core Principles
Principle of Absolute Isolation
- main branch history is clean: the docs/ directory has never appeared in any commit on the main branch
- docs branch is completely independent: created using an orphan branch, with no common history with main
- Cannot be merged silently: since there is no common ancestor, an accidental merge will immediately error out
- Local read-only use: feature branches temporarily obtain documentation via git archive, without tracking modifications
Operation Steps
Step 1: Create an orphan documentation branch (initial setup)
Pre-checks:
# 确认 main 分支干净
git checkout main
git status # 应无未提交更改
# 验证 main 从未包含 docs/
git log main -- docs/
# 若返回空，说明干净 ✅
Create an orphan branch:
# 创建全新的、无历史的 docs 分支
git checkout --orphan docs
# 清空工作区（orphan 分支会保留当前文件）
git rm -rf .
# 创建 docs 目录和文档
mkdir docs
echo "# Development Guide" > docs/dev-guide.md
# 添加更多文档...
# 提交文档（docs 分支的第一个提交，与 main 无任何关联）
git add docs/
git commit -m "chore(docs): initial local documentation"
# 回到 main，确认 docs/ 不存在
git checkout main
ls -la # 应看不到 docs/
Step 2: Safely use documentation in feature branches
Create a feature branch and extract documentation:
# 1. 从 main 创建功能分支
git checkout main
git checkout -b feat-user-login
# 2. 从 docs 分支提取文档（只读，不跟踪）
git archive docs docs/ | tar -x -C .
# 现在 ./docs/ 存在，但 Git 视为 untracked 文件
Configure protection (key step):
# 3. 将 docs/ 加入本地排除列表，防止误提交
echo "docs/" >> .git/info/exclude
# 验证：docs/ 不应出现在 git status 的待提交列表中
git status
Commit after development is complete:
# 4. 明确添加代码目录（避免 git add . 风险）
git add src/ tests/ scripts/ # 根据项目结构调整
# 或：如果用了 git add .，则移除 docs/
git add .
git reset docs/ 2>/dev/null || true
# 5. 提交代码（docs/ 不会被包含）
git commit -m "feat: implement user login"
# 6. 合并回 main
git checkout main
git merge feat-user-login
# 7. 清理
git branch -d feat-user-login
rm -rf docs/ # 删除临时拷贝
Step 3: Verify isolation status
Check main branch cleanliness:
# 检查 main 是否 ever 包含 docs/
git log --all --full-history -- docs/
# 更严格地，只查 main：
git log main -- docs/
# 如果返回空，说明 main 完全干净 ✅
Verify docs branch independence:
# 确认 docs 与 main 无共同祖先
git merge-base main docs
# 应返回空（无共同祖先）
Resource Index
- Git command reference: see references/git-commands.md(when to read: when specific command syntax is needed)
- Branch strategy details: see references/branch-strategy.md(when to read: when you need to understand the strategy principles)
Security Mechanism Description
Why is this absolutely safe?
| Risk Scenario | How It Is Avoided |
|---|---|
| docs/ is committed to main | main has never had docs/, and .git/info/exclude prevents git add . |
| docs/ enters main via merge | docs is an orphan branch with no common ancestor with main, so merge will error out |
| The agent mistakenly modifies documentation, causing loss | The original documentation always remains in the independent docs branch, and the local copy can be discarded at will |
| History pollution | The entire commit history of main does not contain docs/, satisfying the "must not be saved" requirement |
Branch Structure Visualization
main → [A] — [B] — [C] (无 docs/)
↑
└─ 所有 feat-* 从此分出，临时拷贝 docs/，用完即删
docs → [D] (孤立分支，只有 docs/，与 A/B/C 无关联)
Notes
- Do not create docs/ on main and then delete it: that will still remain in the history
- If docs/ was already committed to main early in the project: it is recommended to use git filter-repo to completely purge the history
- For new projects: using --orphan to create the docs branch is the simplest and safest starting point
- Verify regularly: use verification commands to regularly check the cleanliness of the main branch
Usage Examples
Example 1: New project initialization
# 新项目，main 分支已存在
git checkout main
# 创建孤立 docs 分支
git checkout --orphan docs
git rm -rf .
mkdir docs
echo "# API Documentation" > docs/api.md
git add docs/
git commit -m "chore(docs): add API documentation"
# 回到 main
git checkout main
Example 2: Daily development workflow
# 开始新功能
git checkout -b feat-payment-module
# 获取最新文档
git archive docs docs/ | tar -x -C .
echo "docs/" >> .git/info/exclude
# 开发...
# 参考 docs/api.md 进行开发
# 提交（docs/ 自动被排除）
git add src/
git commit -m "feat: implement payment module"
# 清理
git checkout main
git merge feat-payment-module
git branch -d feat-payment-module
rm -rf docs/
Example 3: Update documentation
# 切换到 docs 分支更新文档
git checkout docs
vim docs/api.md # 修改文档
git add docs/
git commit -m "docs: update API documentation"
# 回到 main
git checkout main