141 lines
7.5 KiB
Markdown
141 lines
7.5 KiB
Markdown
|
||
好的，没问题。这是一份为您和您的同事量身定制的 Git 和 Gitea 使用说明文档，专注于日常开发流程，并融入了 VSCode 的操作提示。
|
||
|
||
---
|
||
|
||
# Git 与 Gitea 协作开发指南
|
||
|
||
本文档面向已经完成环境搭建的同事，旨在帮助大家快速上手使用 Git 和公司内网的 Gitea 服务平台进行日常代码协作。我们将使用 VSCode 作为主要开发工具。
|
||
|
||
## 1. 核心概念速览
|
||
|
||
理解以下几个概念，后续操作会更容易：
|
||
|
||
* **仓库 (Repository)**：一个项目所有的文件和历史记录，就是一个仓库。分为：
|
||
* **远程仓库 (Remote)**：存放在 Gitea 服务器上的仓库，是大家共享和协作的中心。
|
||
* **本地仓库 (Local)**：存放在你自己电脑上的仓库，是你个人工作的地方。
|
||
* **克隆 (Clone)**：将远程仓库**完整地下载**到你的本地电脑，这是开始参与一个已有项目的第一步。
|
||
* **提交 (Commit)**：将你对代码的修改**打包并保存**到本地仓库的历史记录中。每次提交都需要附上一个简短的说明，描述这次修改的内容。
|
||
* **推送 (Push)**：将你在本地仓库的提交**上传**到远程仓库（Gitea），让其他同事能看到你的工作成果。
|
||
* **拉取 (Pull)**：将远程仓库（Gitea）上其他人的最新提交**下载并合并**到你的本地仓库，让你的本地代码保持最新。
|
||
* **分支 (Branch)**：一条独立的工作线。通常，`main` (或 `master`) 分支是稳定可用的主分支。开发新功能或修复 Bug 时，我们会在新的分支上进行，完成后再合并回主分支，这样可以避免影响主分支的稳定性。
|
||
|
||
---
|
||
|
||
## 2. 日常工作流程 (核心)
|
||
|
||
这是你最常用到的操作序列。
|
||
|
||
### 场景：开始一天的工作 - 获取最新代码
|
||
|
||
1. **打开项目**：在 VSCode 中打开你的项目文件夹。
|
||
2. **拉取最新代码**：
|
||
* **方法一 (VSCode GUI)**：点击左侧活动栏的**源代码管理**图标（或按 `Ctrl+Shift+G`），在界面顶部点击 **...** 更多操作菜单，选择 **拉取 (Pull)**。
|
||
* **方法二 (命令行)**：打开 VSCode 的集成终端 (<kbd>Ctrl</kbd>+<kbd>`</kbd>)，输入：
|
||
```bash
|
||
git pull origin main
|
||
```
|
||
（请将 `main` 替换为你实际使用的分支名，如 `master`, `develop` 等）
|
||
|
||
> **最佳实践**：每天开始工作前和提交代码前，先执行 `git pull`，可以有效减少代码冲突。
|
||
|
||
### 场景：提交你的工作 - 保存并分享你的修改
|
||
|
||
当你完成一部分代码后，需要将其提交并推送到远程仓库。
|
||
|
||
1. **暂存更改 (Staging)**：在 VSCode 的“源代码管理”面板，可以看到所有更改的文件。点击文件旁的 **+** 号，或点击更改列表上方的 **+** 号，将文件放入“暂存区”。这表示你准备要提交这些文件。
|
||
|
||
|
||
|
||
2. **提交 (Commit)**：在上方的输入框内填写清晰的提交信息（例如：“修复了用户登录的逻辑错误”），然后按 <kbd>Ctrl</kbd>+<kbd>Enter</kbd> (Windows) 或 <kbd>CMD</kbd>+<kbd>Enter</kbd> (Mac) 提交。你也可以点击输入框旁的 ✓ 图标进行提交。
|
||
|
||
|
||
|
||
3. **推送 (Push)**：提交只是保存在了本地。需要点击 **源代码管理** 面板顶部的 **...** 菜单，选择 **推送 (Push)**，才能将本次提交上传到 Gitea。
|
||
|
||
* **命令行等效操作**：
|
||
```bash
|
||
git add . # 暂存所有更改
|
||
git commit -m "你的提交信息" # 提交到本地仓库
|
||
git push origin your-branch-name # 推送到远程分支
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 分支管理策略
|
||
|
||
我们通常采用 **功能分支工作流**。
|
||
|
||
### 创建新功能分支
|
||
|
||
不要在 `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`)。
|
||
2. **在 Gitea 上创建 PR**：
|
||
* 浏览器打开你的项目 Gitea 页面（例如：`http://your-gitea-company.com/your-group/your-project`）。
|
||
* 通常会看到一条提示，显示你刚刚推送的分支，点击 **创建拉取请求** 按钮。
|
||
* 或者，切换到 **Pull Requests** 标签页，点击 **New Pull Request**。
|
||
3. **填写 PR 信息**：
|
||
* **标题**：清晰概括本次 PR 的内容。
|
||
* **描述**：详细说明修改内容、原因（可选）测试情况等。可以贴上相关任务的链接。
|
||
* 选择正确的**基础分支** (通常是 `main`) 和**对比分支** (你的功能分支)。
|
||
4. **申请评审**：可以指定一位或多位同事对你的代码进行评审（Review）。
|
||
5. **合并 PR**：通过评审后，你或具有权限的同事可以在 Gitea Web 界面上操作合并（Merge）。合并后，你的功能就正式成为了主代码的一部分。
|
||
|
||
---
|
||
|
||
## 4. 常见问题与解决
|
||
|
||
### 1. 推送失败：提示“非快进式更新”
|
||
|
||
**原因**：在你推送之前，远程分支已经有了新的提交，导致你的本地历史落后于远程历史。
|
||
|
||
**解决**：
|
||
1. 先执行 `git pull origin your-branch-name` 拉取远程的最新代码。
|
||
2. Git 会自动尝试合并。如果合并顺利，解决可能出现的冲突后，再次执行 `git push`。
|
||
|
||
### 2. 拉取时出现“合并冲突”
|
||
|
||
**原因**：你修改的代码和别人修改的代码在同一位置，Git 无法自动判断该保留谁的。
|
||
|
||
**解决**：
|
||
1. **不要慌张**，这是协作中的正常现象。
|
||
2. 在 VSCode 中，冲突文件会被特殊标记。打开冲突文件，你会看到类似这样的内容：
|
||
```python
|
||
<<<<<<< HEAD
|
||
这是你本地修改的内容
|
||
=======
|
||
这是远程分支上别人的修改
|
||
>>>>>>> a1b2c3d4...
|
||
```
|
||
3. **手动解决**：与冲突代码的作者沟通，决定保留哪一部分，或者进行整合。删除 `<<<<<<<`, `=======`, `>>>>>>>` 这些标记。
|
||
4. **标记为已解决**：在 VSCode 的“源代码管理”面板，解决完所有冲突后，点击该文件右边的 **...**，选择 **标记为已解决**。
|
||
5. **完成合并**：像往常一样，执行提交（这次提交信息通常是合并自动生成的）和推送。
|
||
|
||
---
|
||
|
||
## 5. VSCode 小贴士
|
||
|
||
* **图形化界面**：多使用“源代码管理”视图的按钮和右键菜单，大部分操作都可以点击完成，无需记忆命令。
|
||
* **差异对比**：在“源代码管理”面板点击更改的文件，可以直观地看到具体修改了哪些代码（绿色是新增，红色是删除）。
|
||
* **集成终端**：VSCode 内置了终端 (<kbd>Ctrl</kbd>+<kbd>`</kbd>)，可以直接在其中输入 Git 命令，无需切换窗口。
|
||
|
||
## 获取帮助
|
||
|
||
* 本地的命令帮助：在终端输入 `git help <命令>`，如 `git help push`
|
||
|
||
希望这份指南能帮助你顺畅地开始协作开发！ |