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 中：
    *   按 <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> 打开命令面板。
    *   输入 `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] 修复首页图片无法加载的问题`。
    *   按 <kbd>Ctrl</kbd>+<kbd>Enter</kbd> (Mac: <kbd>CMD</kbd>+<kbd>Enter</kbd>) 提交到**本地仓库**。

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

---

## 4. VSCode 高效技巧

1.  **图形化界面**：多使用“源代码管理”视图和右键菜单，大部分操作无需命令。
2.  **差异对比**：点击更改的文件，可直观查看代码行级别的变化（绿色新增，红色删除）。
3.  **行内暂存**：在更改文件的代码行号旁边，点击 **+** 号可以只暂存该行的修改，而不是整个文件，用于提交精炼的更改。
4.  **集成终端**：使用 VSCode 内置终端 (<kbd>Ctrl</kbd>+<kbd>`</kbd>) 执行 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`。


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