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