Git 文档隔离管理

快速开始

5 分钟上手

# 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

日常使用（每次开发）

# 获取文档进行开发
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/

任务目标

• 本 Skill 用于: 管理本地开发文档，确保 docs/ 目录绝不进入 main 分支的 Git 历史
• 能力包含: 创建孤立文档分支、安全提取文档、分支合并防护、文档隔离验证
• 触发条件: 当用户需要在本地维护开发文档但不想将其提交到主干分支时使用

核心原则

绝对隔离原则

• main 分支历史干净: docs/ 目录从未出现在 main 分支的任何提交中
• docs 分支完全独立: 使用 orphan 分支创建，与 main 无共同历史
• 无法静默合并: 由于无共同祖先，误操作 merge 会立即报错
• 本地只读使用: 功能分支通过 git archive 临时获取文档，不跟踪修改

操作步骤

步骤 1: 创建孤立文档分支（首次设置）

前置检查:

# 确认 main 分支干净
git checkout main
git status  # 应无未提交更改

# 验证 main 从未包含 docs/
git log main -- docs/
# 若返回空，说明干净 ✅

创建孤立分支:

# 创建全新的、无历史的 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/

步骤 2: 在功能分支中安全使用文档

创建功能分支并提取文档:

# 1. 从 main 创建功能分支
git checkout main
git checkout -b feat-user-login

# 2. 从 docs 分支提取文档（只读，不跟踪）
git archive docs docs/ | tar -x -C .

# 现在 ./docs/ 存在，但 Git 视为 untracked 文件

配置防护（关键步骤）:

# 3. 将 docs/ 加入本地排除列表，防止误提交
echo "docs/" >> .git/info/exclude

# 验证：docs/ 不应出现在 git status 的待提交列表中
git status

开发完成后提交:

# 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/   # 删除临时拷贝

步骤 3: 验证隔离状态

检查 main 分支干净性:

# 检查 main 是否 ever 包含 docs/
git log --all --full-history -- docs/

# 更严格地，只查 main：
git log main -- docs/

# 如果返回空，说明 main 完全干净 ✅

验证 docs 分支独立性:

# 确认 docs 与 main 无共同祖先
git merge-base main docs
# 应返回空（无共同祖先）

资源索引

• Git 命令参考: 见 references/git-commands.md(何时读取: 需要具体命令语法时)
• 分支策略详解: 见 references/branch-strategy.md(何时读取: 需要理解策略原理时)

安全机制说明

为什么这样绝对安全？

风险场景	如何被规避
docs/ 被提交到 main	main 从未有 docs/，且 .git/info/exclude 阻止 git add .
docs/ 通过 merge 进入 main	docs 是 orphan 分支，与 main 无共同祖先，merge 会报错
智能体误改文档导致丢失	原始文档始终在独立的 docs 分支中，本地副本可随意丢弃
历史污染	main 的整个提交历史都不含 docs/，满足"不能保存"的要求

分支结构可视化

main       → [A] — [B] — [C]          (无 docs/)
               ↑
               └─ 所有 feat-* 从此分出，临时拷贝 docs/，用完即删

docs       → [D]                      (孤立分支，只有 docs/，与 A/B/C 无关联)

注意事项

• 不要在 main 上创建过 docs/ 再删除: 那仍会留在历史中
• 如果项目早期已在 main 提交过 docs/: 建议用 git filter-repo 彻底清除历史
• 对于新项目: 用 --orphan 创建 docs 分支是最简单、最安全的起点
• 定期验证: 使用验证命令定期检查 main 分支的干净性

使用示例

示例 1: 新项目初始化

# 新项目，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

示例 2: 日常开发流程

# 开始新功能
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/

示例 3: 更新文档

# 切换到 docs 分支更新文档
git checkout docs
vim docs/api.md  # 修改文档
git add docs/
git commit -m "docs: update API documentation"

# 回到 main
git checkout main