Manlink_Doc/Readme/git.md

Git 与 Gitea 协作开发指南

文档说明

本文档面向公司内部已配置好开发环境（VSCode、Git、Gitea）的同事，旨在规范并指导如何使用 Git 和公司内网的 Gitea 服务平台进行高效的日常代码协作。本文档不包含环境安装与部署内容。

1. 术语表 (Glossary)

术语/缩写	全称/解释	说明
Repository (Repo)	仓库	一个项目所有的文件和历史记录。可以理解为你的项目文件夹及其所有变更记忆。
Local	本地	指存储在你个人电脑上的仓库。
Remote	远程	指存储在服务器（如 Gitea）上的仓库，是团队协作的中心。
Clone	克隆	将远程仓库完整下载到本地的操作。这是获取项目代码的起点。
Commit	提交	将你的代码变更打包并保存到本地仓库历史记录中的操作。每次提交都需要一条说明信息。
Push	推送	将你本地仓库的提交上传到远程仓库的操作，使你的工作成果对他人可见。
Pull	拉取	将远程仓库的最新提交下载并合并到本地的操作，用于同步他人的工作成果。
Fetch	获取	从远程仓库下载最新的变更信息到本地，但不会自动合并到你的工作文件中。让你可以查看他人进度，再决定是否拉取。
Branch	分支	一条独立的开发线。主分支（如 main）应保持稳定，新功能应在特性分支上开发。
Merge	合并	将一个分支的修改整合到另一个分支的操作（例如，将功能分支合并到主分支）。
Pull Request (PR)	拉取请求	一个核心协作流程。它是 Gitea 等平台的功能，用于发起代码合并请求，并进行代码评审（Code Review）、讨论和自动化检查。
Issue	议题/问题	用于跟踪任务、功能请求和 Bug。每个 Issue 应有清晰的标题和描述，可以被分配、分类和讨论。
.gitignore	-	一个特殊的配置文件，用于告诉 Git 哪些文件或目录不需要纳入版本控制（如日志文件、编译产物、本地配置文件等）。
Conflict	冲突	当多个人修改了同一文件的同一区域时，Git 无法自动合并，需要人工介入解决的情况。
HEAD	-	通常指向你当前所在的分支的最新提交，可以理解为“你当前的工作目录状态”。

---

2. 核心工作流程

2.1. 初始化：克隆仓库 (Clone)

参与一个已有项目的第一步是获取代码。

1. 打开浏览器，访问项目的 Gitea 页面。
2. 找到并点击 克隆 按钮，复制提供的 URL（通常以 http://... 开头）。
3. 在 VSCode 中：
   • 按 Ctrl+Shift+P 打开命令面板。
   • 输入 Git: Clone 并选择。
   • 粘贴刚才复制的 URL，按回车。
   • 选择本地存储项目的目录。
4. 克隆完成后，VSCode 会提示你打开克隆的项目。

2.2. 每日循环：获取与同步

每天开始工作前，务必先同步远程的最新代码到本地，以避免冲突。

• 推荐操作：拉取 (Pull)

  • VSCode GUI: 点击左侧源代码管理图标 -> 点击顶部 ... -> 选择 拉取 (Pull)。
  • 终端命令: git pull origin <当前分支名>

• 可选操作：获取 (Fetch) + 拉取

  • 如果你想先查看别人改了什么再决定是否合并，可以先 获取：
    • VSCode GUI: ... -> 获取 (Fetch)
    • 终端命令: git fetch
  • 获取后，你可以在 VSCode 的左下角分支状态栏或源代码管理视图看到远程的更新提示，然后再决定拉取。

2.3. 开发流程：基于分支的策略

我们采用 功能分支工作流。严禁直接在 main 或 develop 等主分支上直接开发新功能。

1. 创建新分支：

   • 确保你当前在主分支上（例如 main），并且已经执行了 拉取 操作。
   • 点击 VSCode 窗口左下角的分支名 -> 选择 创建新分支... -> 输入分支名 -> 回车。
   • 分支命名规范：
     • 功能：feat/简短描述，例如 feat/user-auth
     • Bug修复：fix/问题描述，例如 fix/login-crash
     • 文档：docs/更新内容，例如 docs/api-update
     • 热修复：hotfix/紧急问题，例如 hotfix/prod-issue

2. 在新分支上开发：在此分支上完成你的编码、测试等工作。

3. 提交更改：

   • 在 VSCode 的“源代码管理”面板，看到所有更改的文件。
   • 点击文件旁的 + 号或将文件拖到“暂存更改”区域。
   • 在上方输入框撰写清晰的提交信息。
     • 格式建议：[类型] 简短描述，例如 [Feat] 增加微信登录功能 或 [Fix] 修复首页图片无法加载的问题。
   • 按 Ctrl+Enter (Mac: CMD+Enter) 提交到本地仓库。

4. 推送分支：

   • 首次推送新分支时，VSCode 会提示你发布（推送）分支。点击提示或点击源代码管理顶部的 ... -> 推送。
   • 这将把你的本地分支和所有提交推送到 Gitea，并在远程创建同名分支。

2.4. 协作流程：发起拉取请求 (Pull Request)

完成功能开发后，需要将代码合并回主分支。

1. 推送最终代码：确保你已将分支的所有提交都推送到 Gitea。
2. 在 Gitea 上创建 PR：
   • 浏览器打开你的项目 Gitea 页面。
   • 通常页面上会有你刚推送分支的提示，直接点击 创建拉取请求 按钮。
   • 或手动切换到 Pull Requests 标签页 -> New Pull Request。
3. 填写 PR 信息：
   • 标题：清晰概括 PR 内容，建议使用提交信息的格式。
   • 描述：
     • 详细说明修改内容、动机、测试方法。
     • 关键：关联 Issue。在描述中输入 # 后会提示相关的 Issue，选择即可。使用 Closes #15, Fixes #32 等关键词，合并后可自动关闭对应 Issue。
     • 如有界面变动，最好附上截图或屏幕录制。
   • 选择正确的基础分支 (如 main) 和头部分支 (你的功能分支)。
4. 发起评审：可以指定相关同事进行评审（Review）。
5. 处理评审意见：评审者可能会在 PR 中提出评论。请根据意见在本地修改代码，然后再次提交并推送，新的提交会自动追加到该 PR 中。
6. 合并与清理：
   • 通过评审后，由有权限的成员在 Gitea 上操作合并。
   • 合并后，可以在 Gitea 上删除已合并的功能分支（通常有选项）。
   • 本地清理：切换回 main 分支 -> 拉取最新代码 -> 删除本地已合并的功能分支 (git branch -d feat/your-branch)。

---

3. 常见问题与解决方案

3.1. 推送失败：非快进式更新

现象：git push 时提示 ! [rejected] error: failed to push some refs...

原因：在你推送之前，远程分支已经被别人更新了。

解决：

1. 执行 git pull origin <你的分支名> 拉取远程的最新代码并合并到本地。
2. 解决可能出现的合并冲突（见下节）。
3. 再次执行 git push。

3.2. 合并冲突 (Conflict)

现象：执行 git pull 或合并分支时，提示 CONFLICT (content)。

解决：

1. 保持冷静，冲突是协作的正常部分。
2. 在 VSCode 中，冲突文件会被突出显示。打开文件，你会看到 Git 的冲突标记：

   <<<<<<< HEAD
   这是你本地修改的代码
   =======
   这是远程分支上的代码
   >>>>>>> commit-hash...
   

3. 沟通与决策：与冲突代码的作者（可通过 Git 历史或团队沟通工具联系）讨论，决定保留哪一部分代码，或进行整合。
4. 手动解决：
   • 删除不需要的代码块。
   • 必须删除所有冲突标记 (<<<<<<<, =======, >>>>>>>)。
5. 标记为已解决：
   • 在 VSCode 的“源代码管理”面板，解决后的文件会出现在“已暂存的更改”中。
   • 右键点击该文件 -> 选择阶段更改（如果未自动暂存）。
6. 完成合并：
   • 像正常提交一样，输入一个合并提交信息（如 Merge branch 'main' into feat/xxx）。
   • 提交并推送。

---

4. VSCode 高效技巧

1. 图形化界面：多使用“源代码管理”视图和右键菜单，大部分操作无需命令。
2. 差异对比：点击更改的文件，可直观查看代码行级别的变化（绿色新增，红色删除）。
3. 行内暂存：在更改文件的代码行号旁边，点击 + 号可以只暂存该行的修改，而不是整个文件，用于提交精炼的更改。
4. 集成终端：使用 VSCode 内置终端 (Ctrl+`) 执行 Git 命令，工作流无缝衔接。
5. 时间线视图：点击单个文件，在编辑区下方可以看到该文件的时间线，展示所有的历史提交记录，方便追溯变更。

5. 最佳实践总结

1. 勤提交：小步快跑，频繁提交。每次提交只做一个明确的修改，并写好清晰的提交信息。
2. 勤拉取：开始工作前、提交代码前，先 pull 一下，与主线保持同步。
3. 开分支：任何新功能或 Bug 修复，都从新建分支开始。
4. 早提 PR：功能未完全完成但希望早期评审时，可以创建 Draft PR（Gitea 支持）。
5. 看提示：密切关注 VSCode 左下角分支状态栏的同步状态提示（如 ↑3 代表有3个本地提交未推送，↓2 代表有2个远程提交未拉取）。
6. 用 Issues：开发前先创建 Issue 来规划和跟踪任务，并在 PR 中关联它们。

获取帮助

• 本地帮助：在终端输入 git help <命令>，如 git help commit。

祝您编码愉快，协作顺利！