Add Readme Getting Started Markdown

Readme/git.md

@@ -1,141 +1,171 @@
-
-好的，没问题。这是一份为您和您的同事量身定制的 Git 和 Gitea 使用说明文档，专注于日常开发流程，并融入了 VSCode 的操作提示。
-
----
-
 # Git 与 Gitea 协作开发指南
 
-本文档面向已经完成环境搭建的同事，旨在帮助大家快速上手使用 Git 和公司内网的 Gitea 服务平台进行日常代码协作。我们将使用 VSCode 作为主要开发工具。
+## 文档说明
 
-## 1. 核心概念速览
+本文档面向公司内部已配置好开发环境（VSCode、Git、Gitea）的同事，旨在规范并指导如何使用 Git 和公司内网的 Gitea 服务平台进行高效的日常代码协作。本文档不包含环境安装与部署内容。
 
-理解以下几个概念，后续操作会更容易：
+## 1. 术语表 (Glossary)
 
-*   **仓库 (Repository)**：一个项目所有的文件和历史记录，就是一个仓库。分为：
-    *   **远程仓库 (Remote)**：存放在 Gitea 服务器上的仓库，是大家共享和协作的中心。
-    *   **本地仓库 (Local)**：存放在你自己电脑上的仓库，是你个人工作的地方。
-*   **克隆 (Clone)**：将远程仓库**完整地下载**到你的本地电脑，这是开始参与一个已有项目的第一步。
-*   **提交 (Commit)**：将你对代码的修改**打包并保存**到本地仓库的历史记录中。每次提交都需要附上一个简短的说明，描述这次修改的内容。
-*   **推送 (Push)**：将你在本地仓库的提交**上传**到远程仓库（Gitea），让其他同事能看到你的工作成果。
-*   **拉取 (Pull)**：将远程仓库（Gitea）上其他人的最新提交**下载并合并**到你的本地仓库，让你的本地代码保持最新。
-*   **分支 (Branch)**：一条独立的工作线。通常，`main` (或 `master`) 分支是稳定可用的主分支。开发新功能或修复 Bug 时，我们会在新的分支上进行，完成后再合并回主分支，这样可以避免影响主分支的稳定性。
+| 术语/缩写 | 全称/解释 | 说明 |
+| :--- | :--- | :--- |
+| **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. 核心工作流程
 
-这是你最常用到的操作序列。
+### 2.1. 初始化：克隆仓库 (Clone)
 
-### 场景：开始一天的工作 - 获取最新代码
+参与一个已有项目的第一步是获取代码。
 
-1.  **打开项目**：在 VSCode 中打开你的项目文件夹。
-2.  **拉取最新代码**：
-    *   **方法一 (VSCode GUI)**：点击左侧活动栏的**源代码管理**图标（或按 `Ctrl+Shift+G`），在界面顶部点击 **...** 更多操作菜单，选择 **拉取 (Pull)**。
-    *   **方法二 (命令行)**：打开 VSCode 的集成终端 (<kbd>Ctrl</kbd>+<kbd>`</kbd>)，输入：
-        ```bash
-        git pull origin main
-        ```
-        （请将 `main` 替换为你实际使用的分支名，如 `master`, `develop` 等）
+1.  打开浏览器，访问项目的 Gitea 页面。
+2.  找到并点击 **克隆** 按钮，复制提供的 URL（通常以 `http://...` 开头）。
+3.  在 VSCode 中：
+    *   按 <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> 打开命令面板。
+    *   输入 `Git: Clone` 并选择。
+    *   粘贴刚才复制的 URL，按回车。
+    *   选择本地存储项目的目录。
+4.  克隆完成后，VSCode 会提示你打开克隆的项目。
 
-> **最佳实践**：每天开始工作前和提交代码前，先执行 `git pull`，可以有效减少代码冲突。
+### 2.2. 每日循环：获取与同步
 
-### 场景：提交你的工作 - 保存并分享你的修改
+**每天开始工作前**，务必先同步远程的最新代码到本地，以避免冲突。
 
-当你完成一部分代码后，需要将其提交并推送到远程仓库。
+*   **推荐操作：拉取 (Pull)**
+    *   **VSCode GUI**: 点击左侧源代码管理图标 -> 点击顶部 **...** -> 选择 **拉取 (Pull)**。
+    *   **终端命令**: `git pull origin <当前分支名>`
 
-1.  **暂存更改 (Staging)**：在 VSCode 的“源代码管理”面板，可以看到所有更改的文件。点击文件旁的 **+** 号，或点击更改列表上方的 **+** 号，将文件放入“暂存区”。这表示你准备要提交这些文件。
+*   **可选操作：获取 (Fetch) + 拉取**
+    *   如果你想先查看别人改了什么再决定是否合并，可以先 **获取**：
+        *   **VSCode GUI**: ... -> **获取 (Fetch)**
+        *   **终端命令**: `git fetch`
+    *   获取后，你可以在 VSCode 的左下角分支状态栏或源代码管理视图看到远程的更新提示，然后再决定拉取。
 
-    
+### 2.3. 开发流程：基于分支的策略
 
-2.  **提交 (Commit)**：在上方的输入框内填写清晰的提交信息（例如：“修复了用户登录的逻辑错误”），然后按 <kbd>Ctrl</kbd>+<kbd>Enter</kbd> (Windows) 或 <kbd>CMD</kbd>+<kbd>Enter</kbd> (Mac) 提交。你也可以点击输入框旁的 ✓ 图标进行提交。
+我们采用 **功能分支工作流**。严禁直接在 `main` 或 `develop` 等主分支上直接开发新功能。
 
-    
+1.  **创建新分支**：
+    *   确保你当前在**主分支**上（例如 `main`），并且已经执行了 **拉取** 操作。
+    *   点击 VSCode 窗口左下角的分支名 -> 选择 **创建新分支...** -> 输入分支名 -> 回车。
+    *   **分支命名规范**：
+        *   功能：`feat/简短描述`，例如 `feat/user-auth`
+        *   Bug修复：`fix/问题描述`，例如 `fix/login-crash`
+        *   文档：`docs/更新内容`，例如 `docs/api-update`
+        *   热修复：`hotfix/紧急问题`，例如 `hotfix/prod-issue`
 
-3.  **推送 (Push)**：提交只是保存在了本地。需要点击 **源代码管理** 面板顶部的 **...** 菜单，选择 **推送 (Push)**，才能将本次提交上传到 Gitea。
+2.  **在新分支上开发**：在此分支上完成你的编码、测试等工作。
 
-    *   **命令行等效操作**：
-        ```bash
-        git add .                         # 暂存所有更改
-        git commit -m "你的提交信息"       # 提交到本地仓库
-        git push origin your-branch-name  # 推送到远程分支
-        ```
+3.  **提交更改**：
+    *   在 VSCode 的“源代码管理”面板，看到所有更改的文件。
+    *   点击文件旁的 **+** 号或将文件拖到“暂存更改”区域。
+    *   在上方输入框撰写**清晰的提交信息**。
+        *   **格式建议**：`[类型] 简短描述`，例如 `[Feat] 增加微信登录功能` 或 `[Fix] 修复首页图片无法加载的问题`。
+    *   按 <kbd>Ctrl</kbd>+<kbd>Enter</kbd> (Mac: <kbd>CMD</kbd>+<kbd>Enter</kbd>) 提交到**本地仓库**。
 
----
+4.  **推送分支**：
+    *   首次推送新分支时，VSCode 会提示你发布（推送）分支。点击提示或点击源代码管理顶部的 **...** -> **推送**。
+    *   这将把你的本地分支和所有提交推送到 Gitea，并在远程创建同名分支。
 
-## 3. 分支管理策略
+### 2.4. 协作流程：发起拉取请求 (Pull Request)
 
-我们通常采用 **功能分支工作流**。
+完成功能开发后，需要将代码合并回主分支。
 
-### 创建新功能分支
-
-不要在 `main` 分支上直接开发！为新功能或 Bug 修复创建一个独立分支。
-
-1.  **查看当前分支**：VSCode 窗口的左下角会显示当前分支名（例如：`main`）。
-2.  **创建新分支**：点击左下角的分支名，在弹出的顶栏中选择 **创建新分支...**，输入分支名（例如：`feat/user-profile-avatar`），然后按回车。VSCode 会自动切换到新分支。
-
-    
-
-    *   **分支命名建议**：
-        *   功能：`feat/简短描述`
-        *   Bug修复：`fix/问题描述`
-        *   文档：`docs/更新内容`
-
-### 合并分支与 Pull Request (PR)
-
-当你完成开发并测试通过后，需要将分支合并回 `main` 分支。我们通过 Gitea 的 **Pull Request (PR)** 功能来完成，这是代码评审的关键环节。
-
-1.  **推送你的分支**：确保你已经将本地分支推送到了 Gitea (`git push origin your-branch-name`)。
+1.  **推送最终代码**：确保你已将分支的所有提交都推送到 Gitea。
 2.  **在 Gitea 上创建 PR**：
-    *   浏览器打开你的项目 Gitea 页面（例如：`http://your-gitea-company.com/your-group/your-project`）。
-    *   通常会看到一条提示，显示你刚刚推送的分支，点击 **创建拉取请求** 按钮。
-    *   或者，切换到 **Pull Requests** 标签页，点击 **New Pull Request**。
+    *   浏览器打开你的项目 Gitea 页面。
+    *   通常页面上会有你刚推送分支的提示，直接点击 **创建拉取请求** 按钮。
+    *   或手动切换到 **Pull Requests** 标签页 -> **New Pull Request**。
 3.  **填写 PR 信息**：
-    *   **标题**：清晰概括本次 PR 的内容。
-    *   **描述**：详细说明修改内容、原因（可选）测试情况等。可以贴上相关任务的链接。
-    *   选择正确的**基础分支** (通常是 `main`) 和**对比分支** (你的功能分支)。
-4.  **申请评审**：可以指定一位或多位同事对你的代码进行评审（Review）。
-5.  **合并 PR**：通过评审后，你或具有权限的同事可以在 Gitea Web 界面上操作合并（Merge）。合并后，你的功能就正式成为了主代码的一部分。
+    *   **标题**：清晰概括 PR 内容，建议使用提交信息的格式。
+    *   **描述**：
+        *   详细说明修改内容、动机、测试方法。
+        *   **关键：关联 Issue**。在描述中输入 `#` 后会提示相关的 Issue，选择即可。使用 `Closes #15`, `Fixes #32` 等关键词，合并后可自动关闭对应 Issue。
+        *   如有界面变动，最好附上截图或屏幕录制。
+    *   选择正确的**基础分支** (如 `main`) 和**头部分支** (你的功能分支)。
+4.  **发起评审**：可以指定相关同事进行评审（Review）。
+5.  **处理评审意见**：评审者可能会在 PR 中提出评论。请根据意见在本地修改代码，然后再次**提交并推送**，新的提交会自动追加到该 PR 中。
+6.  **合并与清理**：
+    *   通过评审后，由有权限的成员在 Gitea 上操作合并。
+    *   合并后，可以在 Gitea 上**删除已合并的功能分支**（通常有选项）。
+    *   **本地清理**：切换回 `main` 分支 -> 拉取最新代码 -> 删除本地已合并的功能分支 (`git branch -d feat/your-branch`)。
 
 ---
 
-## 4. 常见问题与解决
+## 3. 常见问题与解决方案
 
-### 1. 推送失败：提示“非快进式更新”
+### 3.1. 推送失败：非快进式更新
 
-**原因**：在你推送之前，远程分支已经有了新的提交，导致你的本地历史落后于远程历史。
+**现象**：`git push` 时提示 `! [rejected] error: failed to push some refs...`
+
+**原因**：在你推送之前，远程分支已经被别人更新了。
 
 **解决**：
-1.  先执行 `git pull origin your-branch-name` 拉取远程的最新代码。
-2.  Git 会自动尝试合并。如果合并顺利，解决可能出现的冲突后，再次执行 `git push`。
+1.  执行 `git pull origin <你的分支名>` 拉取远程的最新代码并合并到本地。
+2.  解决可能出现的**合并冲突**（见下节）。
+3.  再次执行 `git push`。
 
-### 2. 拉取时出现“合并冲突”
+### 3.2. 合并冲突 (Conflict)
 
-**原因**：你修改的代码和别人修改的代码在同一位置，Git 无法自动判断该保留谁的。
+**现象**：执行 `git pull` 或合并分支时，提示 `CONFLICT (content)`。
 
 **解决**：
-1.  **不要慌张**，这是协作中的正常现象。
-2.  在 VSCode 中，冲突文件会被特殊标记。打开冲突文件，你会看到类似这样的内容：
+1.  **保持冷静**，冲突是协作的正常部分。
+2.  在 VSCode 中，冲突文件会被突出显示。打开文件，你会看到 Git 的冲突标记：
     ```python
     <<<<<<< HEAD
-    这是你本地修改的内容
+    这是你本地修改的代码
     =======
-    这是远程分支上别人的修改
-    >>>>>>> a1b2c3d4...
+    这是远程分支上的代码
+    >>>>>>> commit-hash...
     ```
-3.  **手动解决**：与冲突代码的作者沟通，决定保留哪一部分，或者进行整合。删除 `<<<<<<<`, `=======`, `>>>>>>>` 这些标记。
-4.  **标记为已解决**：在 VSCode 的“源代码管理”面板，解决完所有冲突后，点击该文件右边的 **...**，选择 **标记为已解决**。
-5.  **完成合并**：像往常一样，执行提交（这次提交信息通常是合并自动生成的）和推送。
+3.  **沟通与决策**：与冲突代码的作者（可通过 Git 历史或团队沟通工具联系）讨论，决定保留哪一部分代码，或进行整合。
+4.  **手动解决**：
+    *   删除不需要的代码块。
+    *   **必须删除**所有冲突标记 (`<<<<<<<`, `=======`, `>>>>>>>`)。
+5.  **标记为已解决**：
+    *   在 VSCode 的“源代码管理”面板，解决后的文件会出现在“已暂存的更改”中。
+    *   右键点击该文件 -> **选择阶段更改**（如果未自动暂存）。
+6.  **完成合并**：
+    *   像正常提交一样，输入一个合并提交信息（如 `Merge branch 'main' into feat/xxx`）。
+    *   提交并推送。
 
 ---
 
-## 5. VSCode 小贴士
+## 4. VSCode 高效技巧
 
-*   **图形化界面**：多使用“源代码管理”视图的按钮和右键菜单，大部分操作都可以点击完成，无需记忆命令。
-*   **差异对比**：在“源代码管理”面板点击更改的文件，可以直观地看到具体修改了哪些代码（绿色是新增，红色是删除）。
-*   **集成终端**：VSCode 内置了终端 (<kbd>Ctrl</kbd>+<kbd>`</kbd>)，可以直接在其中输入 Git 命令，无需切换窗口。
+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 push`
+*   **本地帮助**：在终端输入 `git help <命令>`，如 `git help commit`。
 
-希望这份指南能帮助你顺畅地开始协作开发！
+
+祝您编码愉快，协作顺利！