# Git 同步与上传规范

## 📋 概述
本文档规范了 MkDocs 知识库项目的 Git 同步和上传流程，确保团队协作高效、代码版本可控。

## 🎯 目标
- 统一团队 Git 操作流程
- 减少代码冲突和版本问题
- 确保代码及时同步和备份
- 建立规范的提交和推送习惯

## 🔄 日常同步流程

### 1. 开始工作前（拉取最新代码）
```bash
# 进入项目目录
cd D:\mkdocs

# 检查当前状态
git status

# 拉取远程最新代码
git pull origin master

# 确认同步完成
git log --oneline -5
```

### 2. 工作过程中（定期同步）
```bash
# 查看是否有远程更新
git fetch origin

# 比较本地和远程差异
git log origin/master..master  # 本地有远程没有的提交
git log master..origin/master  # 远程有本地没有的提交

# 如果有远程更新，先拉取
git pull --rebase origin master
```

### 3. 提交更改（本地保存）
```bash
# 查看更改的文件
git status

# 添加所有更改（或指定文件）
git add .                      # 添加所有更改
# 或
git add <文件名>               # 添加指定文件

# 提交更改（描述要清晰）
git commit -m "描述：做了什么修改，为什么修改"

# 提交示例：
# git commit -m "文档：添加用户认证模块API文档"
# git commit -m "修复：修正MkDocs构建配置错误"
# git commit -m "功能：新增Docker部署指南"
```

### 4. 推送到服务器（共享代码）
```bash
# 先拉取最新代码（避免冲突）
git pull origin master

# 如果有冲突，解决冲突后提交
# git add .
# git commit -m "解决合并冲突"

# 推送到远程服务器
git push origin master

# 验证推送成功
git log --oneline -3
```

## 📤 上传新文件流程

### 1. 添加新文档文件
```bash
# 创建新文件（如：新功能文档）
# 文件路径：D:\mkdocs\docs\龙虾openclaw\新功能.md

# 添加到Git跟踪
git add docs\龙虾openclaw\新功能.md

# 或添加整个目录
git add docs\龙虾openclaw\
```

### 2. 添加新目录结构
```bash
# 创建新目录
mkdir -p docs\龙虾openclaw\新模块

# 添加目录和文件
git add docs\龙虾openclaw\新模块\

# 如果目录中有需要忽略的文件，先更新.gitignore
```

### 3. 提交和推送
```bash
# 提交新文件
git commit -m "新增：龙虾openclaw新模块文档"

# 推送到服务器
git push origin master
```

## 🚨 冲突处理流程

### 1. 检测冲突
```bash
# 拉取时发现冲突
git pull origin master
# 输出：CONFLICT (content): Merge conflict in <文件名>
```

### 2. 解决冲突
```bash
# 查看冲突文件
git status

# 手动编辑冲突文件
# 文件内容会显示：
# <<<<<<< HEAD
# 本地内容
# =======
# 远程内容
# >>>>>>> commit-hash

# 保留需要的内容，删除标记
# 保存文件
```

### 3. 完成冲突解决
```bash
# 标记冲突已解决
git add <冲突文件>

# 继续合并
git commit -m "解决合并冲突：<文件描述>"

# 完成推送
git push origin master
```

## 📝 提交信息规范

### 格式要求
```
<类型>: <简短描述>

<详细描述（可选）>
```

### 类型说明
- **文档**: 文档新增、修改、删除
- **功能**: 新功能、特性添加
- **修复**: Bug修复、问题解决
- **优化**: 性能优化、代码重构
- **配置**: 配置文件修改
- **依赖**: 依赖包更新
- **测试**: 测试用例相关
- **样式**: CSS、样式修改

### 示例
```
文档: 添加Git同步规范文档

- 详细说明日常同步流程
- 规范提交信息格式
- 添加冲突处理指南
```

## 🔧 高级操作

### 1. 查看提交历史
```bash
# 简洁查看
git log --oneline -10

# 带图表查看
git log --graph --oneline --all

# 查看特定文件历史
git log --oneline -- docs\龙虾openclaw\git同步与上传规范.md
```

### 2. 撤销操作
```bash
# 撤销未提交的修改
git checkout -- <文件名>

# 撤销已add但未commit的文件
git reset HEAD <文件名>

# 修改最后一次提交
git commit --amend -m "新的提交信息"
```

### 3. 分支管理（如需）
```bash
# 创建新分支
git checkout -b feature/新功能

# 切换分支
git checkout master

# 合并分支
git merge feature/新功能

# 删除分支
git branch -d feature/新功能
```

## ⚠️ 注意事项

### 必须遵守
1. **工作前必拉取**：开始工作前必须先 `git pull`
2. **提交前必检查**：提交前用 `git status` 检查更改
3. **描述必清晰**：提交信息必须清晰描述修改内容
4. **冲突必解决**：遇到冲突必须手动解决，不能强制推送

### 建议习惯
1. **小步提交**：频繁提交，每次提交一个完整的小功能
2. **及时推送**：完成一个功能后及时推送到远程
3. **定期同步**：每小时至少同步一次远程代码
4. **备份重要**：重要修改前创建备份分支

### 禁止操作
1. ❌ 不要强制推送 `git push -f`（除非明确知道后果）
2. ❌ 不要提交大文件（超过100MB）
3. ❌ 不要提交敏感信息（密码、密钥等）
4. ❌ 不要提交自动生成的文件（如 `.obsidian/workspace.json`）

## 📊 工作流程图

```mermaid
graph TD
    A[开始工作] --> B[git pull 拉取最新]
    B --> C[编辑文档]
    C --> D[git add 添加更改]
    D --> E[git commit 提交]
    E --> F{是否有远程更新?}
    F -->|是| G[git pull 解决冲突]
    G --> H[git push 推送]
    F -->|否| H
    H --> I[工作完成]
```

## 🛠️ 工具支持

### 1. Git 配置优化
```bash
# 设置用户名和邮箱
git config --global user.name "你的名字"
git config --global user.email "你的邮箱"

# 设置默认编辑器
git config --global core.editor "code --wait"

# 启用颜色显示
git config --global color.ui auto
```

### 2. 别名设置（可选）
```bash
# 添加到 ~/.gitconfig
[alias]
    st = status
    co = checkout
    br = branch
    ci = commit
    df = diff
    lg = log --graph --oneline --all
```

## 📞 问题处理

### 常见问题
1. **权限错误**：检查 Git 服务器访问权限
2. **网络问题**：检查网络连接，确认服务器可达
3. **文件锁定**：关闭正在使用的文件编辑器
4. **磁盘空间**：确保有足够的磁盘空间

### 求助流程
1. 先查看错误信息
2. 搜索错误信息解决方案
3. 联系团队技术支持（FE工程师）
4. 提供完整错误日志

---

**最后更新**：2026-03-29  
**维护者**：李建华（FE前端工程师）  
**适用项目**：D:\mkdocs 知识库项目