基于 Git 的团队协作指南

在开始之前，请确保你已经完成注册 GitHub 账号并安装配置好 Git。如果还没有完成这些步骤，请参考 Windows 上的 Git 安装与配置指南 进行操作。

本指南旨在帮助初学者了解基于 Git 的团队协作工作流，涵盖从基本概念到实际操作的完整流程。无论你是参与开源项目还是团队开发，这篇文档都能为你提供清晰的指导。

概念

在个人项目中，你只需管理自己本地的仓库和提交。 但在团队协作中，多个开发者需要共同管理一个远程仓库。每位成员都会将这个远程仓库克隆到自己的本地，然后在自己的工作副本上进行开发，最后将完成的更改合并回共享的远程仓库。

在学习团队协作的 Git 工作流程之前，应先熟悉以下基本概念：

  • 远程仓库（Remote Repository）：托管在服务器上的 Git 仓库，团队成员通过它进行协作。常见的远程仓库托管服务有 GitHub、GitLab 和 Bitbucket。
  • 克隆（Clone）：从远程仓库复制一份完整的仓库到本地。
  • 分支（Branch）：在同一个仓库中创建独立的开发线，允许多个开发者同时工作而不互相干扰。
  • 拉取（Pull）：从远程仓库获取最新的更改并合并到本地分支。
  • 推送（Push）：将本地的更改上传到远程仓库。
  • 合并（Merge）：将一个分支的更改整合到另一个分支中。
    • 快进合并（Fast-forward Merge）：当目标分支没有新的提交时，Git 直接将目标分支指向源分支的最新提交。
    • 非快进合并（Non-fast-forward Merge）：当目标分支有新的提交时，Git 会创建一个新的合并提交来整合两个分支的更改。
  • 冲突（Conflict）：当多个开发者对同一文件的同一部分进行了不同的更改时，Git 无法自动合并这些更改，需要手动解决冲突。

Issue 和 Pull Request

在团队协作中，Issue 和 Pull Request 是两个重要的工具，用于管理项目的任务和代码更改。

Issue

Issue 是用于跟踪项目中的任务、功能请求、错误报告等事项的工具。每个 Issue 都有一个唯一的编号，包含标题、描述、标签和评论等信息。团队成员可以通过 Issue 来讨论和协作解决问题。

Pull Request

Pull Request（PR，拉取请求）是用于提交代码更改的工具。当你完成了某个功能或修复了一个问题，并希望将这些更改合并到主分支或其他分支中时，你需要创建一个 Pull Request。PR 包含了更改的详细信息、相关的 Issue 链接以及审查和讨论的功能。

Fork 工作流

如果你要参与的不是自己拥有管理权限的项目，通常需要先 Fork 该项目。

Fork

Fork 是在远程仓库托管服务（如 GitHub）上创建一个项目的副本。这样，你就可以在自己的账户下拥有该项目的完整控制权，进行修改和实验，而不会影响原始项目。

在 GitHub 中，点击仓库页面右上角的 “Fork” 按钮，即可将该仓库 Fork 到你的账户下。

Clone

Clone 是将远程仓库复制到本地的过程。无论是 Fork 还是直接参与的项目，你都需要克隆仓库到本地进行开发。

获得自己 Fork 的仓库地址后，使用以下命令克隆仓库：

1
git clone https://github.com/<你的用户名>/<仓库名>.git

为了让本地仓库能拉取原始上游仓库（即你 Fork 的来源仓库）的最新更改，通常还需要添加上游远程仓库：

1
2
3
git remote add upstream git@github.com:<原始作者用户名>/<原始仓库名>.git
# 查看远程仓库列表，确认添加成功
git remote -v

Pull Request

当你完成了某个功能或修复了一个问题，并希望将这些更改合并到原始项目中时，你需要创建一个 Pull Request。

  1. 同步上游仓库

    在创建 PR 之前，确保你的本地仓库是最新的。首先，拉取上游仓库的更改：

    1
    2
    3
    4
    5
    git fetch upstream
    # 切换到主分支
    git checkout main
    # 合并上游主分支的更改
    git merge upstream/main

  2. 创建新分支

    主分支通常用于稳定的代码，建议在主分支之外创建一个新的分支来进行开发：

    1
    git checkout -b feature/your-feature-name

  3. 提交更改

    在新分支上进行开发，完成后提交更改：

    1
    2
    3
    git add .
    # 提交更改，添加有意义的提交信息
    git commit -m "Added new feature"

  4. 推送分支

    将你的分支推送到远程仓库：

    1
    git push origin feature/your-feature-name

  5. 创建 Pull Request

    • 在 GitHub 上，进入你的 Fork 仓库，点击 “Compare & pull request” 按钮。
    • 填写 PR 的标题和描述，说明你做了哪些更改以及为什么这些更改是必要的。
    • 确保目标分支是原始仓库的主分支（通常是 main 或 master）。
    • 提交 PR 后，项目维护者会审查你的更改，并可能会提出修改建议。根据反馈进行相应的修改和更新 PR，直到 PR 被合并。

  6. 合并 PR

    一旦 PR 被批准，项目维护者会将你的更改合并到原始仓库中。你可以在 PR 页面上看到合并状态。

  7. 删除分支

    PR 合并后，你可以删除本地和远程的开发分支：

    1
    2
    3
    4
    # 删除本地分支
    git branch -d feature/your-feature-name
    # 删除远程分支
    git push origin --delete feature/your-feature-name

直接协作工作流

如果你有权限直接向远程仓库推送更改，可以使用直接协作工作流。

  1. 克隆仓库

    首先，克隆远程仓库到本地：

    1
    2
    3
    4
    5
    6
    7
    git clone <远程仓库地址>

    # 进入仓库目录
    cd <仓库名>

    # 查看远程仓库列表，确认 origin 已正确设置
    git remote -v

  2. 创建分支

    在开始新功能或修复之前，创建一个新的分支：

    1
    git checkout -b feature/your-feature-name

  3. 提交更改

    在新分支上进行开发，完成后提交更改：

    1
    2
    git add .
    git commit -m "Implemented new feature"

  4. 拉取最新更改

    在推送之前，确保你的分支是最新的：

    1
    2
    3
    4
    5
    6
    7
    git checkout main
    git pull origin main
    git checkout feature/your-feature-name
    # 方法一：使用 rebase 将你的更改应用在最新的主分支上
    git rebase main
    # 方法二：使用 merge 将主分支的更改合并到你的分支上
    git merge main

    关于 rebase 和 merge 的选择：

    • rebase 会将你的提交重新应用在最新的主分支上，保持提交历史的线性，但可能会导致冲突需要手动解决。
    • merge 会创建一个新的合并提交来整合主分支的更改，保留了完整的提交历史，但可能会使历史变得复杂。

  5. 推送分支

    将你的分支推送到远程仓库：

    1
    2
    3
    4
    5
    # 首次推送分支时，使用以下命令设置上游分支
    git push -u origin feature/your-feature-name

    # 后续推送可以直接使用
    # git push

  6. 创建合并请求（可选）

    如果团队使用代码审查流程，可以在远程仓库托管服务（如 GitHub）上创建一个合并请求（Pull Request），让其他成员审查你的更改。

  7. 合并分支

    一旦更改被审查并批准，可以将分支合并到主分支：

    1
    2
    git checkout main
    git merge feature/your-feature-name

    然后，推送更新后的主分支到远程仓库：

    1
    git push origin main

  8. 删除分支

    合并完成后，可以删除本地和远程的开发分支：

    1
    2
    3
    4
    5
    6
    # 删除本地分支
    git branch -d feature/your-feature-name
    # 删除远程分支
    git push origin --delete feature/your-feature-name
    # 如果远程分支已经删除，可以使用以下命令清理本地的远程分支引用
    git fetch --prune

合并冲突

在团队协作中，合并冲突是不可避免的。当多个开发者对同一文件的同一部分进行了不同的更改时，Git 无法自动合并这些更改，就会产生冲突。

例如，当你和另一个开发者同时修改了 README.md 文件的同一行并尝试合并时，Git 会标记冲突部分：

1
2
3
4
5
<<<<<<< HEAD
这是你的更改。
=======
这是另一个开发者的更改。
>>>>>>> feature/other-developer

避免冲突

  • 频繁拉取远程分支更新：在开发过程中，定期使用 git pull 或 git fetch 确保本地分支与远程分支保持同步。
  • 小而频繁的提交：将更改分成小的、独立的提交，减少冲突的可能性。
  • 明确分工：团队成员应尽量避免同时修改同一文件的同一部分。

完成冲突解决后，保存文件并提交解决冲突的更改：

1
2
git add README.md
git commit -m "Resolved merge conflict in README.md"

协作规范

以下内容不是强制要求，但使用这些规范可以帮助团队更高效地协作：

分支命名规范

有意义的分支名称可以帮助团队成员快速理解分支的目的和内容。以下是一些常见的分支命名规范：

  • 主分支：main 或 master，用于存放稳定的代码
  • 功能分支：feature/描述性名称，例如 feature/user-authentication
  • 修复分支：fix/描述性名称，例如 fix/login-bug
  • 发布分支：release/版本号，例如 release/v1.0.0
  • 热修复分支：hotfix/描述性名称，例如 hotfix/critical-bug
  • 文档分支：docs/描述性名称，例如 docs/update-readme

分支生命周期管理

  • 创建分支：在开发新功能或修复问题时，始终从主分支创建新分支。
  • 合并分支：在分支合并到主分支后，应及时删除本地和远程的开发分支。
  • 保护主分支：启用远程仓库的分支保护规则，防止直接推送到主分支。

提交信息规范

规范的提交信息可以帮助团队成员理解每次更改的目的。提倡 Conventional Commits 规范，提交信息格式如下：

1
2
3
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
  • type：提交的类型，如 feat（新功能）、fix（修复）、docs（文档）、style（格式）、refactor（重构）、test（测试）、chore（杂项）
  • scope：可选，表示影响的范围，如模块或文件名
  • description：简短的描述更改内容
  • body：可选，详细描述更改的原因和内容
  • footer：可选，包含任何相关的元信息，如关闭的 Issue 编号

例如：

1
2
3
feat(auth): add user authentication feature
This commit adds a new user authentication feature using JWT. It includes login and registration endpoints, as well as middleware for protecting routes.
Closes #123

Pull Request 最佳实践

  • 清晰的标题和描述：PR 的标题应简洁明了，描述应详细说明更改的内容和原因。
  • 关联 Issue：如果 PR 解决了某个 Issue，应在描述中引用该 Issue（例如 Closes #123）。
  • 小而专注的 PR：每个 PR 应只包含一个功能或修复，避免过于庞大。
  • 添加测试用例：如果更改涉及代码逻辑，应尽量添加测试用例以验证功能。
  • 审查和反馈：在团队中，PR 应经过至少一名成员的审查，确保代码质量。

通过遵循这些最佳实践，团队协作将更加高效，代码质量也会得到保障。