8  版本控制与协作

9 版本控制与协作

在科学研究中，代码和数据的版本管理是确保可重复性的关键环节。本章介绍 Git 版本控制系统和 GitHub 协作平台的使用方法。

9.1 为什么需要版本控制？

你是否遇到过这样的情况？

论文_v1.docx
论文_v2.docx
论文_v2_导师修改.docx
论文_v3_最终版.docx
论文_v3_最终版_真的最终版.docx
论文_v3_最终版_打死不改了.docx

版本控制系统（Version Control System, VCS）就是为了解决这个问题。Git 是目前最流行的版本控制工具，它能：

  • 记录文件的每一次修改历史
  • 随时回退到任意历史版本
  • 多人协作时自动合并修改
  • 追踪每个人的贡献

9.2 Git 基本概念

9.2.1 仓库（Repository）

仓库（Repository，简称repo）是Git进行版本控制的基本单位，本质上是一个包含完整项目历史记录的文件夹。理解仓库的概念是掌握Git工作流程的第一步。

仓库的两种形态

Git采用分布式架构，每个开发者都拥有完整的项目副本。因此仓库分为两种：

  • 本地仓库（Local Repository）：存储在你电脑硬盘上的项目文件夹。包含完整的版本历史、分支信息和提交记录。即使断网，你也可以查看历史、创建分支、提交代码。

  • 远程仓库（Remote Repository）：托管在GitHub、GitLab等平台上的项目副本。作为团队协作的”中央枢纽”，所有成员通过推送（push）和拉取（pull）操作与远程仓库同步。

仓库的内部结构

当你在项目文件夹中执行git init后，Git会创建一个隐藏的.git目录，这就是仓库的”大脑”。它包含：

.git/
├── objects/      # 存储所有文件的历史版本（压缩存储）
├── refs/         # 存储分支和标签的引用
├── HEAD          # 指向当前所在分支
├── config        # 仓库配置文件
└── hooks/        # Git钩子脚本

为什么需要本地+远程双仓库？

这种设计带来三大优势：

  1. 离线工作能力：即使没有网络，你也可以提交代码、查看历史、创建分支。等有网络时再推送到远程。

  2. 数据安全：每个开发者的本地仓库都是完整备份。即使GitHub服务器宕机，项目数据不会丢失。

  3. 灵活的协作模式：你可以先在本地反复修改提交，确认无误后再推送到远程，避免”半成品”代码污染团队仓库。

生态学案例

某研究团队在野外调查期间，网络信号极差。但因为Git是分布式的，研究人员仍然可以在本地仓库中提交每天的数据清洗脚本和分析代码。两周后回到实验室，一次性将所有提交推送到GitHub，团队其他成员立即看到了完整的工作历史。如果使用集中式版本控制系统（如SVN），这种离线工作模式是不可能实现的。

扩展记录：2026-04-09 | 目标字数：800+

9.2.2 工作区、暂存区、版本库

Git的文件管理采用三层结构，理解这三个区域的关系是掌握Git工作流的关键。很多初学者在这里容易混淆，导致误操作丢失代码。

三层结构详解

工作区（Working Directory）
    ↓  git add
暂存区（Staging Area / Index）
    ↓  git commit
版本库（Repository）
    ↓  git push
远程仓库（Remote）
  1. 工作区（Working Directory）
    • 你能直接看到和编辑的文件
    • 修改文件后，Git会检测到变化（git status显示为红色）
    • 这些修改还没有被Git正式记录
  2. 暂存区（Staging Area）
    • 执行git add后，修改进入暂存区
    • 暂存区是一个”预提交”区域，让你可以精确控制哪些修改进入下一次提交
    • git status显示为绿色
    • 可以多次git add不同文件，最后一次性提交
  3. 版本库（Local Repository）
    • 执行git commit后，暂存区的内容被永久记录到版本库
    • 每次提交都会生成一个唯一的commit ID（SHA-1哈希值）
    • 版本库存储在.git目录中，包含完整的项目历史
  4. 远程仓库（Remote Repository）
    • 执行git push后，本地版本库的提交被推送到GitHub等远程平台
    • 团队成员可以通过git pull获取你的提交

为什么需要暂存区？

暂存区的设计看似多余，实则非常巧妙。它允许你：

  • 分批提交：假设你同时修改了5个文件，但只想提交其中3个，可以只git add这3个文件。
  • 检查修改：在提交前，可以用git diff --staged查看暂存区的内容，确认无误后再提交。
  • 撤销操作：如果git add错了文件，可以用git restore --staged <file>从暂存区移除，而不影响工作区的修改。

常见误区

很多初学者以为git add就是”保存”，git commit是”上传”。实际上： - git add只是”标记”要提交的文件 - git commit才是真正的”保存”到版本库 - git push才是”上传”到远程

生态学案例

某研究生在分析土壤微生物数据时，同时修改了3个文件： - data_cleaning.R（数据清洗脚本） - statistical_analysis.R（统计分析脚本） - plot_diversity.R（多样性可视化脚本）

他发现statistical_analysis.R还有bug未修复，但data_cleaning.R已经完善。此时他可以：

# 只提交清洗脚本
git add data_cleaning.R
git commit -m "完成数据清洗流程"

# 继续修改统计脚本，修复bug后再提交
# （此时plot_diversity.R的修改仍在工作区，不受影响）

这种灵活性让你可以保持提交历史的清晰，每次提交只包含一个逻辑完整的修改。

扩展记录：2026-04-09 | 目标字数：800+

9.3 Git 基础命令详解

9.3.1 初始化仓库

有两种方式开始使用 Git 管理你的项目。一种是创建一个全新的仓库，另一种是从已有远程仓库克隆一个副本。

方式一：在现有项目中初始化

如果你已经有了项目文件夹，想用 Git 管理它，执行以下命令：

# 进入项目文件夹
cd ~/my-ecology-project

# 初始化 Git 仓库（会创建隐藏的 .git 文件夹）
git init

# 查看状态
git status

# 查看 Git 版本（确认安装成功）
git --version

执行 git init 后，Git 会在当前文件夹中创建一个隐藏的 .git 子文件夹。这个文件夹包含了 Git 管理项目所需的所有元数据。不要手动修改或删除 .git 文件夹中的任何内容。

方式二：从远程仓库克隆

如果你想参与一个已有项目，或者想基于别人的代码开始工作，使用克隆：

# 克隆 GitHub 上的仓库到本地
git clone https://github.com/username/repo-name.git

# 克隆到指定文件夹名（如果不指定，文件夹名默认为仓库名）
git clone https://github.com/username/repo-name.git my-project

# 克隆特定分支
git clone --branch feature/data-cleaning https://github.com/username/repo-name.git

# 克隆后自动进入项目文件夹
cd repo-name

克隆操作会创建一个完整的本地副本，包括所有的提交历史。你可以完全自由地在本地提交、创建分支，远程仓库不会受到影响（除非你主动推送）。

克隆的深度选项

# 浅克隆（只包含最近一次提交，适合大型仓库）
git clone --depth 1 https://github.com/username/repo-name.git

# 浅克隆后如果需要完整历史
git fetch --unshallow

生态学案例

某课程小组的项目仓库已经在 GitHub 上创建好了（由组长创建）。组员不需要自己初始化，只需要克隆到本地：

git clone https://github.com/group-leader/ecology-data-project.git
cd ecology-data-project

克隆完成后，组员就有了一个完整的本地副本，可以开始创建分支、编写代码了。

扩展记录：2026-04-09 | 目标字数：800+ ### HTTPS vs SSH

克隆或连接 GitHub 仓库时，有两种协议可以选择：HTTPS 和 SSH。两者的主要区别在于认证方式和操作便捷性。

HTTPS 方式

# 使用 HTTPS 克隆
git clone https://github.com/username/repo-name.git

优点： - 配置简单，初学者友好 - 在大多数网络环境下都能正常工作 - 不需要生成 SSH 密钥

缺点： - 每次推送（push）都需要输入用户名和密码（或 Access Token） - 如果启用双重认证（TFA），操作会更繁琐

SSH 方式

# 使用 SSH 克隆
git clone git@github.com:username/repo-name.git

优点： - 配置一次后，所有操作无需输入密码 - 安全性更高，不存在密码泄露风险 - 适合频繁推送的开发者

缺点： - 需要生成 SSH 密钥对并添加到 GitHub - 在某些网络环境下可能需要额外配置代理

SSH 配置步骤（Windows/macOS/Linux）

# 1. 检查是否已有 SSH 密钥
ls -la ~/.ssh/

# 2. 如果没有，生成新的 SSH 密钥（使用邮箱）
ssh-keygen -t ed25519 -C "your_email@example.com"

# 3. 一路回车，使用默认设置
#    生成的文件在 ~/.ssh/id_ed25519（私钥）和 ~/.ssh/id_ed25519.pub（公钥）

# 4. 将公钥添加到 GitHub
#    复制公钥内容：cat ~/.ssh/id_ed25519.pub
#    登录 GitHub → Settings → SSH and GPG keys → New SSH key → 粘贴

# 5. 测试连接
ssh -T git@github.com
#    如果看到 "Hi username! You've successfully authenticated" 就成功了

课程推荐

对于初学者，推荐使用 HTTPS 方式，配置简单，上手快。在 Positron 中使用 Git 时，HTTPS 方式也是默认选项。等到熟悉 Git 基本操作后，可以切换到 SSH 方式，体验无密码推送的便捷。

扩展记录：2026-04-09 | 目标字数：800+ ### 查看状态与历史

git status 和 git log 是 Git 中使用频率最高的两个命令。前者告诉你”现在发生了什么”，后者告诉你”过去发生了什么”。在数据分析项目中养成经常使用这两个命令的习惯，可以让你对项目状态了如指掌。

git status：项目的实时快照

# 查看当前状态（最常用命令）
git status

# 简洁模式（只显示已修改的文件名）
git status -s

# 显示所有分支的简略信息
git status -sb

# 只显示已跟踪且有修改的文件
git status -uno

git status 的输出会告诉你：当前在哪个分支、有哪些文件被修改（但未暂存）、有哪些文件已暂存（但未提交）。红色表示工作区修改，绿色表示已暂存。

git log：提交历史的时光机

# 查看提交历史（简洁版，每行一条提交）
git log --oneline

# 查看提交历史（详细版，包含作者、日期）
git log

# 查看最近 5 次提交
git log -5

# 查看某个文件的修改历史
git log --oneline -- scripts/analysis.R

# 查看图形化分支历史（推荐）
git log --oneline --graph --all

# 只看某个人的提交
git log --author="张三"

# 查看特定时间范围的提交
git log --since="2027-03-01" --until="2027-04-01"

示例输出：

$ git log --oneline
a3f2b1c 添加物种多样性分析脚本
7d8e9f0 修复数据清洗中的 NA 处理问题
4c5d6e7 更新 README 说明文档
1a2b3c4 初始提交：项目结构搭建

每个提交ID（a3f2b1c）是该提交内容的 SHA-1 哈希值的前7位，具有唯一性。

git log 的高级用法

# 美化输出格式
git log --pretty=format:"%h %an %s" --graph

# 按提交数量限制（常用于快速浏览）
git log -10 --oneline

# 查看某次提交的详细内容
git show a3f2b1c

# 查看两次提交之间的所有文件变化
git diff 1a2b3c4..a3f2b1c --stat

# 查看某个文件在特定版本的内容
git show a3f2b1c:scripts/analysis.R | head -20

如何阅读陌生仓库的提交历史

拿到一个陌生的 Git 仓库时，建议按以下顺序浏览：

# 1. 看项目结构
git ls-tree -r --name-only HEAD | head -20

# 2. 看提交历史（最近10条）
git log -10 --oneline

# 3. 看都有哪些分支
git branch -a

# 4. 看 README（了解项目是什么）
git show HEAD:README.md | head -50

生态学案例

某实验室的研究生接手了师兄的项目，需要在原有数据清洗脚本基础上继续分析。他通过 git log --oneline 快速浏览了师兄两年的提交历史，发现：项目经历了”基础框架→异常值处理→多样性指数计算→可视化”的开发过程。git show a3f2b1c 看到具体的物种名称标准化方法。通过 git blame scripts/data_cleaning.R 发现某个关键函数是另一位已毕业师兄写的。这些信息帮助他快速理解项目脉络，避免了”从头再来”的浪费。

扩展记录：2026-04-09 | 目标字数：800+ # 查看当前状态（最常用命令） git status

10 查看提交历史（简洁版）

git log –oneline

11 查看提交历史（详细版，包含作者、日期）

git log

12 查看最近 5 次提交

git log -5

13 查看某个文件的修改历史

git log –oneline – scripts/analysis.R

14 查看图形化分支历史

git log –oneline –graph –all


**示例输出：**

$ git log –oneline a3f2b1c 添加物种多样性分析脚本 7d8e9f0 修复数据清洗中的 NA 处理问题 4c5d6e7 更新 README 说明文档 1a2b3c4 初始提交：项目结构搭建


### 添加与提交

在 Git 中，工作流程是"修改→暂存→提交"三步曲。`git add` 将修改放入暂存区，`git commit` 将暂存区内容永久写入版本库。每次提交都应是一个独立的、完整的逻辑单元。

**为什么要先暂存再提交？**

暂存区的设计看似多余，实则非常巧妙。假设你修改了 5 个文件，其中 3 个属于"数据清洗"功能，另外 2 个属于"可视化"功能。你应该分两次提交，而不是一次提交所有修改。这样做的好处是：提交历史更清晰，每个提交都可以独立回滚。

**git add 命令详解**

```bash
# 添加单个文件到暂存区
git add scripts/analysis.R

# 添加多个文件（用空格分隔）
git add scripts/analysis.R data/processed/clean_data.csv

# 添加整个文件夹
git add scripts/

# 添加所有修改（谨慎使用！会添加当前目录及子目录下所有修改）
git add .

# 添加所有 .R 文件（通配符）
git add *.R

# 查看将要提交的内容（推荐在 git add 后执行）
git diff --staged

# 从暂存区移除文件（取消暂存，但不删除文件）
git restore --staged scripts/analysis.R

git commit 命令详解

# 基本提交
git commit -m "添加物种多样性分析脚本"

# 同时提交所有已追踪文件的修改（不包括新文件）
git commit -am "修复数据清洗脚本中的错误"

# 修改最后一次提交（追加修改到上一个提交，常用于提交信息写错）
git commit --amend -m "正确的提交信息"

# 提交时显示差异
git commit -v

提交的最佳实践

  1. 每次提交一个逻辑单元：如果同时修改了 5 个文件，但它们分别属于 3 个不同的功能，应该分成 3 次提交。这样做的好处是：如果某次提交引入了错误，可以单独回滚这次提交，而不影响其他修改。

  2. 提交信息要描述”做了什么”：

    • ✅ feat(data): 添加土壤 pH 异常值检测函数
    • ✅ fix(viz): 修复散点图图例重叠问题
    • ❌ 更新 或 fix

  3. 频繁提交：每完成一个小功能就提交，不要等到一天结束才提交。频繁提交可以让回溯历史更精确，冲突解决更容易。

  4. 先测试再提交：确保代码能正常运行后再提交，不要把有语法错误的代码推送到共享分支。

生态学案例

某研究生在分析马尾松林土壤数据时，采用”上午提交一次，下午提交一次”的策略。某天上午，他完成了土壤 pH 数据的异常值检测，提交信息为 feat(data): 添加 pH 异常值检测，标记了 3 个离群点。当天下午继续工作时，他不小心删除了 data_cleaning.R 中的一个关键函数。由于上午已经提交，他直接 git checkout HEAD~1 -- scripts/data_cleaning.R 恢复到上午版本，丢失的工作量只有半天而不是一整天。这就是频繁提交的价值——提交历史就是你的安全网。

扩展记录：2026-04-09 | 目标字数：800+ ### git add . 的风险

git add . 是一个看似方便但潜藏风险的命令。它会递归添加当前目录及所有子目录下的所有修改文件到暂存区，这意味着你可能在不知情的情况下提交了不该提交的内容。在数据采集与分析项目中，这个问题尤为突出，因为我们经常会产生大量临时文件、中间结果和敏感数据。

常见的误提交场景：

  1. 大型数据文件：野外采集的原始数据（如高分辨率影像、大型表格）可能有几百MB甚至几GB，一旦提交到Git仓库，会严重拖慢克隆和拉取速度，且难以彻底删除。

  2. 临时文件：R语言会自动生成.Rhistory、.RData等临时文件，这些文件包含你的工作历史和环境变量，不仅占用空间，还可能泄露敏感信息（如API密钥、数据库密码）。

  3. 系统文件：操作系统会在文件夹中生成隐藏文件（如Windows的Thumbs.db、macOS的.DS_Store），这些文件对项目毫无意义，却会污染提交历史。

  4. 编译产物：Quarto渲染生成的HTML文件、图表缓存等，这些都可以通过源代码重新生成，不应纳入版本控制。

安全的替代方案：

# 方案一：先查看再添加（推荐）
git status                    # 查看所有修改
git add scripts/analysis.R    # 逐个添加需要的文件
git add data/processed/clean_data.csv

# 方案二：使用通配符精确匹配
git add scripts/*.R           # 只添加R脚本
git add output/figures/*.png  # 只添加PNG图表

# 方案三：配置.gitignore后再使用git add .
# 先创建.gitignore排除不需要的文件类型
echo "*.RData" >> .gitignore
echo "data/raw/" >> .gitignore
git add .                     # 此时才相对安全

生态学案例：某研究生在分析土壤微生物多样性数据时，使用git add .提交了所有文件，结果将500MB的原始测序数据（FASTQ文件）也推送到了GitHub。由于GitHub单文件限制为100MB，推送失败。更糟的是，这些数据已经进入了本地Git历史，即使删除文件，仓库体积仍然庞大。最终不得不使用git filter-branch重写历史，耗费了整整一天时间清理仓库。

最佳实践：

  • 项目初期就创建完善的.gitignore文件（参见本章后续章节）
  • 养成git status → git add <具体文件> → git commit的习惯
  • 对于数据密集型项目，考虑使用Git LFS（Large File Storage）管理大文件
  • 定期检查仓库大小：du -sh .git（Linux/macOS）或Get-ChildItem .git -Recurse | Measure-Object -Property Length -Sum（Windows PowerShell）

扩展记录：2026-04-09 | 目标字数：800+ :::

14.0.1 查看差异

git diff 是 Git 中最强大的调试工具之一，它可以让你查看任意两个版本之间的差异。在数据分析中，diff 可以帮助你理解数据文件、脚本文件的每一行变化。

diff 的基本用法

# 查看工作区与暂存区的差异（还没 git add 的修改）
git diff

# 查看暂存区与版本库的差异（已 git add 但还没 commit 的修改）
git diff --staged

# 查看某个文件的差异
git diff scripts/analysis.R

# 查看两次提交之间的差异
git diff a3f2b1c..7d8e9f0

# 查看某个文件在两次提交间的差异
git diff 1a2b3c4:data/cleaned.csv 7d8e9f0:data/cleaned.csv

diff 输出解读

diff 的输出分为两个部分：文件头和差异内容。差异内容中，以减号-开头的行表示被删除的旧内容，以加号+开头的行表示新增的内容。

diff --git a/scripts/analysis.R b/scripts/analysis.R
index 1a2b3c4..5d6e7f8 100644
--- a/scripts/analysis.R       # 旧版本文件
+++ b/scripts/analysis.R       # 新版本文件
@@ -10,7 +10,7 @@
 # 计算物种多样性指数
-diversity <- diversity(species_matrix, index = "shannon")
+diversity <- diversity(species_matrix, index = "simpson")
@@ -15,3 +15,4 @@
 mean_height <- mean(data\$height, na.rm = TRUE)
+sd_height <- sd(data\$height, na.rm = TRUE)  # 新增行
  • 第 1 行：diff --git a/path b/path 表示比较的是 a/path（旧版本）和 b/path（新版本）
  • 第 2 行：index ... 是文件的 Git 内部索引信息
  • 第 3-4 行：--- 和 +++ 标记旧版本和新版本的文件名
  • 第 5 行：@@ -10,7 +10,7 @@ 表示下面的差异对应原文件第 10 行开始的 7 行和新文件第 10 行开始的 7 行
  • - 开头：被删除的行
  • + 开头：新增的行

在 Positron 中查看 diff

Positron 提供了可视化的 diff 工具，比命令行更直观。打开 Positron，点击 Git 面板中的”Diff”按钮，可以查看当前文件与最新提交的差异。绿色表示新增内容，红色表示删除内容。

生态学案例

某研究生在检查数据清洗脚本的修改时，通过 git diff data_cleaning.R 发现队友不小心将土壤有机碳含量的单位从 g/kg 改成了 g/L。这个单位错误如果没被发现，会导致最终分析结果完全错误。diff 的价值在于：在代码进入正式分析之前，让你看到每一行改了什么。

扩展记录：2026-04-09 | 目标字数：800+ ## 首次使用 Git：初始配置

如果你已经在研究环境搭建中完成了 Git 安装和配置，可以跳过本节。

安装 Git 后，第一件事是告诉 Git 你是谁。这些信息会记录在每次提交中：

# 设置用户名和邮箱（只需执行一次）
git config --global user.name "你的名字"
git config --global user.email "你的邮箱@example.com"

# 验证设置
git config --list
Warning邮箱要和 GitHub 账号一致

Git 的提交记录会永久绑定你配置的邮箱地址。如果这个邮箱与 GitHub 账号不一致，你的提交就不会显示在 GitHub 的贡献图中。

检查配置

# 查看当前 Git 配置
git config --global user.email

# 修改邮箱配置
git config --global user.email "your-github-email@example.com"

注意事项

  • 建议使用 GitHub 注册邮箱作为 user.email
  • 修改后，以前的提交不会自动更新邮箱
  • 可以在 GitHub Settings → Emails 中添加备用邮箱

扩展记录：2026-04-09 | 目标字数：800+ ## 分支管理（Branch Management）

14.0.2 为什么需要分支？

分支是 Git 最强大的功能之一，它允许你在不影响主线代码的情况下进行实验、开发新功能或修复 Bug。对于数据分析项目，分支可以有效隔离不同功能模块的开发，避免”东一块西一块”的混乱状态。

分支的核心价值

在团队协作中，分支解决了两个核心问题：一是并行开发，多个成员可以同时在不同分支上工作，互不干扰；二是代码安全，在 main 或 dev 分支上始终保持可运行的稳定版本。

没有分支会发生什么？

想象一个 5 人小组都在 main 分支上工作：张三正在写数据清洗脚本，李四在改统计分析函数，王五在调整可视化图表。如果不使用分支，他们的提交会交错在一起，产生大量冲突。而且如果某人的代码有 bug，可能会直接影响其他人的工作。

使用分支后：

# 创建功能分支
git checkout -b feature/data-cleaning

# 在功能分支上工作
git add scripts/01-data-cleaning.R
git commit -m "feat: 完成土壤pH异常值处理"

# 推送分支
git push origin feature/data-cleaning

数据分析项目中的分支策略

对于课程项目，建议采用以下分支结构：

main          ← 稳定版本，只有负责人能合并
  └── dev     ← 开发分支，日常提交在此
      ├── feature/data-cleaning   # 张三
      ├── feature/analysis       # 李四
      └── feature/visualization  # 王五

生态学案例

某研究团队在开发一个生物多样性数据库时，没有使用分支。结果是：提交历史混乱不堪，每次推送都有冲突。后来他们采用 main + dev + feature 三层分支结构，所有成员在 feature 分支上开发，完成后合并到 dev，负责人审核后合并到 main。项目效率提高了 3 倍。

扩展记录：2026-04-09 | 目标字数：800+ ### 分支命名规范

良好的分支命名可以让团队成员一眼看出分支的用途和负责人。在团队项目中，分支命名规范比个人项目更重要。

常用的分支前缀

前缀 用途 示例
feature/ 新功能开发 feature/add-diversity-index
bugfix/ Bug 修复 bugfix/fix-na-handling
hotfix/ 紧急修复 hotfix/critical-error
experiment/ 实验性代码 experiment/try-ml-model
docs/ 文档更新 docs/update-readme

团队项目中的命名建议

在课程小组项目中，建议在分支名中加入姓名缩写，便于识别负责人：

# 格式：feature/功能-负责人
feature/data-cleaning-zh     # 张三的数据清洗分支
feature/analysis-ls          # 李四的统计分析分支
feature/viz-wm              # 王五的可视化分支

# 或者使用下划线
bugfix/ph-outlier-zh        # 张三修复pH异常值bug

命名禁忌

  • 不要使用中文字符（某些系统不支持）
  • 不要使用空格和特殊符号（只用 - 或 _）
  • 不要使用过长的名字（保持简洁，20 个字符以内）
  • 不要使用 feature/1 这种无意义的编号

生态学案例

某小组在协作时，有人创建了一个叫”新建分支”的分支，另一个人创建了”test123”分支。结果当 git log 变得很长时，没有人记得住这些分支是干什么的。最后不得不通过询问才知道：“哦，那个 test123 是李四在测试数据清洗函数”。教训是：分支名应该自解释。

扩展记录：2026-04-09 | 目标字数：800+ ### 合并分支

分支开发完成后，需要将功能分支合并回主分支。合并是 Git 中最重要的操作之一，也是最容易产生冲突的环节。理解合并的原理和冲突处理是团队协作的必备技能。

合并的基本流程

# 1. 确保目标分支（通常是 dev 或 main）是最新的
git checkout dev
git pull origin dev

# 2. 合并指定分支
git merge feature/diversity-analysis

# 3. 合并成功后，删除已完成的分支
git branch -d feature/diversity-analysis

# 4. 推送合并结果
git push origin dev

合并的两种类型

  1. 快进合并（Fast-forward）：当目标分支没有新的提交时，Git 直接将指针前移。例如：main 分支没有任何新提交，此时合并 feature 分支，Git 会将 main 指针直接移动到 feature 指针位置，生成一条线性历史。

  2. 三方合并（Three-way）：当目标分支有新提交时，Git 需要将两个分支的最新提交和它们的共同祖先进行三方比较，生成一个新的合并提交。这种合并会产生一个”分叉”的提交历史。

# 查看分支合并历史
git log --oneline --graph --all

# 示例输出：
# *   a3f2b1c Merge branch 'feature/diversity-analysis' into dev
# |\
# | * 7d8e9f0 添加多样性指数计算
# * | 4c5d6e7 修复数据录入错误
# |/
# * 1a2b3c4 初始提交

合并前的检查清单

在合并之前，建议执行以下检查：

# 1. 确认当前分支是正确的目标分支
git branch --show-current

# 2. 查看要合并的分支包含哪些提交
git log feature/diversity-analysis --oneline -10

# 3. 检查是否有未提交的修改（如果有，暂存或提交）
git status

# 4. 确认合并后不会覆盖他人的重要修改
git diff dev..feature/diversity-analysis --stat

删除分支的注意事项

# 删除本地已合并的分支（小写 -d）
git branch -d feature/diversity-analysis

# 强制删除未合并的分支（大写 -D）
git branch -D feature/diversity-analysis

# 删除远程分支
git push origin --delete feature/diversity-analysis

生态学案例

某小组在完成数据清洗分支后，负责人直接点击 GitHub 上的”Merge”按钮，将张三的 data-cleaning 分支合并到 dev。结果合并后李四的统计分析代码全部报错——因为张三在清洗数据时改变了某些列的名称，而李四的代码依赖原来的列名。如果在合并前，张三能在本地先执行 git checkout dev && git merge feature/data-cleaning 并运行李四的代码验证，就不会出现这个问题。教训是：合并前最好在本地测试一下。

扩展记录：2026-04-09 | 目标字数：800+ ### 合并冲突解决

当两个分支修改了同一文件的同一部分时，Git 无法自动合并，会产生合并冲突（Merge Conflict）。这是团队协作中不可避免的问题，掌握冲突解决方法至关重要。

什么情况下会产生冲突？

当两个分支对同一文件进行了修改，且修改的位置”重叠”时，会产生冲突。例如：

  • 分支 A 修改了第 10 行的代码
  • 分支 B 也修改了第 10 行的代码
  • 合并时 Git 不知道该保留哪个

冲突标记的解读

当冲突发生时，Git 会在文件中标记冲突位置：

<<<<<<< HEAD
diversity_index <- diversity(data, index = "shannon")
=======
diversity_index <- diversity(data, index = "simpson")
>>>>>>> feature/diversity-analysis
  • <<<<<<< 和 ======= 之间是当前分支（HEAD）的内容
  • ======= 和 >>>>>>> 之间是要合并的分支的内容

解决冲突的步骤

# 1. 拉取最新代码（可能触发冲突）
git pull origin dev

# 2. 打开冲突文件，删除标记，保留需要的代码
#    或者手动合并两段代码

# 3. 标记冲突已解决
git add scripts/analysis.R

# 4. 完成合并提交
git commit -m "解决合并冲突：统一使用Simpson指数"

# 5. 推送到远程
git push origin dev

使用 Positron 可视化解决冲突

Positron 提供了图形化的冲突解决工具。在 Git 面板中，冲突文件会显示为橙色。点击文件，会打开对比视图，你可以选择保留哪一边的修改，或者手动编辑合并结果。

生态学案例

某小组在合并数据清洗分支时，遇到了这样的冲突：

张三在代码中写 mean(ph, na.rm = TRUE)，李四写 median(ph, na.rm = TRUE)。两人都有道理：均值对异常值敏感，中位数更稳健。解决方法是与队友讨论后决定使用中位数，并在提交信息中说明原因。冲突不是坏事，它强迫团队讨论代码的质量。

扩展记录：2026-04-09 | 目标字数：800+ ### 变基（Rebase）vs 合并（Merge）

Git 有两种将分支合并到一起的方式：Merge（合并）和 Rebase（变基）。理解两者的区别，可以帮助你在不同场景下做出正确选择。

Merge（合并）的特点

Merge 会创建一个新的”合并提交”，将两个分支的历史合并在一起。特点是：

  • 保留完整的分支历史
  • 产生一个分叉的提交图
  • 不会改变现有提交的哈希值
git checkout dev
git merge feature/data-cleaning

# 结果：
# *   Merge branch 'feature/data-cleaning'
# |\
# | * 7d8e9f0 完成数据清洗
# * | 4c5d6e7 修复分析bug
# |/
# * 1a2b3c4 初始提交

Rebase（变基）的特点

Rebase 会将你的提交”移动”到目标分支的末尾，创造一条线性历史。特点是：

  • 历史更简洁，是一条直线
  • 不产生额外的合并提交
  • 会改变提交的哈希值（因为提交基于新的起点重新计算）
git checkout feature/data-cleaning
git rebase dev

# 结果：feature分支的提交被"嫁接"到dev分支的最新提交后面
# 变成线性历史

什么时候用哪个？

场景 推荐方式
团队共享的分支 Merge（不改变历史，更安全）
个人功能分支 Rebase（历史更清晰）
合并前整理提交 Rebase（squash/fixup）
已推送到远程的分支 不要 Rebase

黄金法则：不要对已推送的分支执行 Rebase

因为 Rebase 会改变提交哈希值，如果其他人基于旧的提交继续工作，Rebase 后会产生大量冲突。所以： - 只对本地未推送的提交执行 Rebase - 团队共享的分支（main/dev）永远使用 Merge

生态学案例

某研究生在个人分支上开发数据分析脚本，使用 Rebase 整理了提交历史（将 10 个零碎的提交压缩成 3 个有意义的提交）。后来发现有个分析结果是错误的，需要回滚到某个提交。由于 Rebase 后历史是线性的，他直接用 git revert 或 git reset 就能准确定位到问题提交。这就是 Rebase 的好处：清晰的线性历史让回滚更容易。

扩展记录：2026-04-09 | 目标字数：800+ ## 远程协作（Remote Collaboration）

14.0.3 远程仓库管理

远程仓库是托管在 GitHub 等平台上的项目副本。理解远程仓库的管理操作，可以帮助你更好地进行团队协作。

查看远程仓库信息

# 查看已配置的远程仓库
git remote -v

# 示例输出：
# origin  https://github.com/username/repo.git (fetch)
# origin  https://github.com/username/repo.git (push)
# upstream https://github.com/original/repo.git (fetch)
# upstream https://github.com/original/repo.git (push)

origin 是你fork后的仓库，upstream 是原始仓库（常用于开源贡献场景）。

添加和删除远程仓库

# 添加新的远程仓库
git remote add upstream https://github.com/original/repo.git

# 修改远程仓库URL
git remote set-url origin https://github.com/username/new-repo.git

# 重命名远程仓库
git remote rename origin upstream

# 删除远程仓库
git remote remove upstream

# 查看远程仓库详细信息
git remote show origin

远程仓库的分工

在 fork 模式下，常见的分工是：

  • origin：你自己 fork 的仓库（你有推送权限）
  • upstream：原始仓库（你没有推送权限，但可以拉取更新）
# 同步上游仓库的更新
git fetch upstream
git checkout main
git merge upstream/main
git push origin main

生态学案例

某同学参与了一个开源生态学数据分析项目。原始仓库托管在 GitHub 上，他 fork 了一份到自己的账号。他将原始仓库添加为 upstream，定期同步上游的更新到自己 fork 的仓库。这样既能参与开源项目，又不会干扰原始仓库。

扩展记录：2026-04-09 | 目标字数：800+ ### 推送与拉取

git push 和 git pull 是与远程仓库同步的两个核心操作。掌握它们的正确用法，是团队协作的基础。

git push（推送）

将本地仓库的提交发送到远程仓库，让团队其他成员能看到你的修改。

# 推送到远程仓库
git push origin main

# 第一次推送时设置上游分支（-u）
git push -u origin feature/data-cleaning

# 后续推送只需
git push

# 推送所有分支
git push --all origin

# 删除远程分支（推送空分支）
git push origin --delete old-branch

git pull（拉取）

从远程仓库下载最新提交并自动合并到当前分支。

# 拉取并合并
git pull origin main

# 先拉取再合并（更安全，可以看到远程更新）
git fetch origin
git log HEAD..origin/main  # 查看远程有哪些新提交
git merge origin/main       # 确认后合并

# 拉取并变基（保持线性历史）
git pull --rebase origin dev

pull = fetch + merge

git fetch 只下载远程更新，不合并。git pull = git fetch + git merge。当你不确定远程有什么更新时，先 fetch 查看，再决定是否 merge。

push 前先 pull

在推送本地提交之前，务必先拉取远程最新代码，否则可能产生冲突。标准流程：

# 1. 确保在正确的分支上
git checkout dev

# 2. 拉取最新代码
git pull origin dev

# 3. 解决可能的冲突
# 4. 推送本地提交
git push origin dev

生态学案例

某研究生在分析数据时修改了一个函数，推送到 GitHub 后才发现忘了一个 library() 调用。他立即在本地修复，重新提交，然后 force push（git push --force）覆盖了之前的提交。由于这个分支只有他一个人在用，force push 没有影响其他人。这提醒我们：push 前检查，比 push 后补救更省事。

扩展记录：2026-04-09 | 目标字数：800+ ## 写好提交信息

好的提交信息应该简洁明了，说明”做了什么”：

  • ✅ 添加土壤pH数据清洗脚本
  • ✅ 修复物种名称拼写错误
  • ✅ 更新图表配色方案
  • ❌ 修改了一些东西
  • ❌ update
  • ❌ ...

14.1 GitHub 协作

GitHub 上有多种协作方式，适用于不同场景。我们从最简单的开始。

14.1.1 模式一：Collaborator 直接协作（课程推荐）

这是最简单的 GitHub 协作方式，适合课程小组项目（3-5人）。仓库所有者邀请组员成为 Collaborator，所有人都有直接推送（push）权限。

设置步骤

  1. 仓库所有者：在 GitHub 上创建仓库
  2. 邀请组员：Settings → Collaborators → Add people → 输入组员的 GitHub 用户名
  3. 组员接受邀请：打开邮箱中的邀请链接，点击”Accept invitation”

工作流程

# 组员：克隆仓库到本地
git clone https://github.com/owner-username/repo-name.git
cd repo-name

# 正常工作流程：修改 → 提交 → 推送
git add scripts/analysis.R
git commit -m "feat: 添加多样性分析脚本"
git push origin main

优缺点分析

优点： - 设置简单，无需 fork - 所有成员权限平等 - 推送代码不需要 review（信任机制）

缺点： - 任何人都可以直接修改 main 分支 - 如果成员之间沟通不畅，容易产生冲突 - 不适合陌生人协作的开源项目

为什么课程推荐这种模式？

课程项目是小团队协作，成员之间相互信任，不需要像开源项目那样严格的代码审查流程。Collaborator 模式足够满足课程需求，同时降低了 Git 学习门槛。

生态学案例

某课程小组4人采用 Collaborator 模式。组长创建仓库后邀请了3位组员。大家约定：每周日晚上8点同步一次进度，各自推送代码。由于沟通顺畅，一学期下来没有产生任何冲突。这种模式让小组可以把精力集中在数据分析上，而不是 Git 操作上。

扩展记录：2026-04-09 | 目标字数：800+ ### Collaborator 模式的注意事项

虽然 Collaborator 模式简单直接，但在实际使用中仍有一些坑需要注意。了解这些注意事项，可以让你的团队协作更加顺畅。

约定推送时间，避免冲突

多人同时推送会产生冲突。建议约定： - 每天固定时间推送（如晚上8点） - 开始工作前先 pull 再开始 - 大文件修改前通知其他成员

不要直接在 main 分支上工作

即使你是 Collaborator，也应该先创建功能分支，再合并到 main：

# 创建个人分支
git checkout -b feature/data-cleaning-zh

# 在分支上工作
git add scripts/01-data-cleaning.R
git commit -m "feat(data): 完成pH异常值处理"
git push origin feature/data-cleaning-zh

# 在GitHub上创建Pull Request合并到main

保护 main 分支（可选）

如果想更安全，可以设置 main 分支保护：

  1. 在 GitHub 仓库页面，点击 Settings → Branches
  2. 点击 “Add rule”
  3. 输入 “main”
  4. 勾选 “Require pull request reviews before merging”
  5. 保存

这样即使你是 Collaborator，也必须通过 PR 才能合并到 main，不能直接 push。

生态学案例

某小组使用 Collaborator 模式，但所有人都直接在 main 分支上工作。结果每次推送都冲突不断。后来他们约定：每人创建自己的分支，只在周末合并到 main。冲突次数从每天 5-6 次降为每周 1-2 次。

扩展记录：2026-04-09 | 目标字数：800+ ### 模式二：Fork + Pull Request（开源项目标准流程）

当你想给别人的项目贡献代码，但没有直接推送权限时，使用 Fork + Pull Request（PR）流程。这是开源项目的标准协作方式。

核心概念

  • Fork（派生）：在 GitHub 上将别人的仓库复制一份到自己的账号
  • Pull Request（PR）：请求原仓库所有者拉取你的代码

完整工作流程

# 1. 在 GitHub 上点击 "Fork" 按钮，fork 仓库到自己的账号

# 2. 克隆 fork 后的仓库到本地
git clone https://github.com/your-username/repo-name.git
cd repo-name

# 3. 将原仓库添加为 upstream（用于同步更新）
git remote add upstream https://github.com/original/repo.git

# 4. 创建新分支进行修改
git checkout -b feature/add-analysis

# 5. 修改文件并提交
git add scripts/analysis.R
git commit -m "feat: 添加多样性分析"

# 6. 推送到自己的 fork
git push origin feature/add-analysis

# 7. 在 GitHub 上点击 "Compare & pull request"
#    选择 base: original/main <- head: your-username/feature/add-analysis
#    填写 PR 描述，点击 Create pull request

保持 fork 与上游同步

# 获取上游更新
git fetch upstream

# 切换到 main 分支
git checkout main

# 合并上游更新
git merge upstream/main

# 推送更新到自己的 fork
git push origin main

PR 描述模板

好的 PR 描述应该包含：做了什么、为什么做这个修改、关联的 Issue 编号。

生态学案例

某同学参与了一个开源生物多样性数据库项目。他 fork 了原仓库，添加了一个数据清洗函数，然后提交 PR。维护者 review 后发现代码风格不符合项目规范，提了一些修改意见。同学按意见修改后，PR 被接受，代码合并到了主仓库。这就是开源协作的典型流程。

扩展记录：2026-04-09 | 目标字数：800+ ### 什么时候用哪种模式？

选择正确的协作模式，可以让团队效率最大化。以下是两种模式的适用场景对比。

Collaborator 模式适用场景

场景 说明
课程小组项目 成员之间相互信任的小团队
公司内部项目 同一组织的成员
个人项目 只有一个开发者的仓库
导师-学生项目 导师直接管理仓库

Fork + PR 模式适用场景

场景 说明
开源项目贡献 你不是仓库的 Collaborator
外部合作 与不熟悉的团队协作
需要代码审查 想让修改经过严格审核
实验性修改 不确定是否要合并，想先讨论

本课程推荐的模式

课程期末项目推荐使用 Collaborator 模式，原因：设置简单、流程直接、适合学习阶段、团队规模小不需要复杂的 PR 流程。

生态学案例

某课题组的项目同时采用了两种模式：导师作为仓库 owner，研究生是 Collaborator，可以直接推送代码；而外部合作者则 fork 仓库，通过 PR 贡献代码。这种分层协作模式既保证了内部效率，又规范了外部贡献。

扩展记录：2026-04-09 | 目标字数：800+ ### Issue

Issue 是 GitHub 上的问题追踪工具，可以用来记录任务、讨论方案、跟踪 Bug。在团队项目中，善用 Issue 可以让协作更加有序。

Issue 的常见用途

  • 报告 Bug（如”数据清洗脚本在处理缺失值时崩溃”）
  • 提出新功能建议（如”建议添加多样性指数计算功能”）
  • 讨论项目方向（如”是否应该支持 Excel 文件导入”）
  • 记录待办事项（如”需要补充文献综述”）

创建 Issue

  1. 在 GitHub 仓库页面点击 “Issues” → “New issue”
  2. 填写标题和描述
  3. 可以添加标签（Labels）、指派负责人（Assignees）
  4. 点击 “Submit new issue”

Milestone（里程碑）

可以使用 Milestone 将相关的 Issue 组织在一起，形成一个版本或一个阶段的目标。例如：Milestone “v1.0” 包含完成基础数据清洗功能的 Issue。

生态学案例

某小组在项目中创建了多个 Issue：“数据清洗 → pH 异常值处理”、“数据分析 → 多样性指数计算”、“可视化 → 散点图优化”。每周例会时，他们浏览 Issue 列表，检查哪些完成了，哪些有困难。这种方式让团队工作有据可查，不会遗漏任务。

扩展记录：2026-04-09 | 目标字数：800+ ## 在 Positron 中使用 Git

Positron 内置了 Git 图形界面，不需要记命令行：

14.1.2 创建 Git 项目

在 Positron 中创建 Git 项目是最简单的方式，特别适合不熟悉命令行的初学者。整个过程只需几次点击。

步骤一：通过 Version Control 创建

  1. 打开 Positron
  2. 点击菜单 File → New Project
  3. 选择 “Version Control”
  4. 选择 “Git”
  5. 在 “Repository URL” 中填入 GitHub 仓库地址
  6. 选择本地存放路径
  7. 点击 “Create Project”

步骤二：验证创建成功

创建成功后，Positron 右上角会显示 Git 面板（如果没有，点击 View → Source Control）。Git 面板中会显示 .gitignore、Positron 项目文件等。

步骤三：创建项目结构

# 在 Positron 终端中创建标准文件夹结构
dir.create("data/raw")
dir.create("data/processed")
dir.create("scripts")
dir.create("output/figures")
dir.create("output/tables")
dir.create("report")

# 创建 README.md
file.create("README.md")

# 提交初始结构
# 在 Git 面板中勾选所有新文件，点击 Commit

从现有文件夹创建项目

如果你的代码已经在某个文件夹中，但还没有 Git 版本控制：

  1. 在 Positron 中 File → New Project → Existing Directory
  2. 选择你的文件夹作为项目目录
  3. 勾选 “Create a git repository”
  4. 点击 Create Project

注意事项

  • 项目路径中不要有中文或空格
  • .code-workspace 文件不需要推送到 GitHub，可以添加到 .gitignore
  • 如果 Positron 找不到 Git，检查 Settings → Extensions → Git 是否正确配置了 Git 路径

扩展记录：2026-04-09 | 目标字数：800+ ### 日常操作

在 Positron 中使用 Git 的日常操作非常简单，主要通过 Git 面板完成。以下是标准的工作流程。

Git 面板介绍

Positron 右上角的 Git 面板显示当前仓库中所有被 Git 跟踪的文件。文件前的图标表示状态： - 黄色：文件有修改但未暂存 - 绿色：文件已暂存（已 git add） - 红色：文件有冲突 - 蓝色：新文件（未追踪）

标准工作流程

  1. 在 Positron 中，确认 Git 面板显示文件为黄色（有修改）
  2. 勾选要提交的文件前的复选框（变为绿色，已暂存）
  3. 点击 “Commit” 按钮，打开 Commit 窗口
  4. 输入提交信息，如：“feat(data): 完成土壤pH异常值处理”
  5. 点击 “Commit” 完成提交
  6. 点击 “Push” 推送到远程

撤销操作

  • 撤销工作区的修改：在 Positron 中点击 “Revert” 按钮
  • 取消暂存：取消勾选文件
  • 修改最后一次提交信息：勾选 “Amend” 选项

生态学案例

某研究生每次修改代码后都会在 Positron 中 Commit。他说这个习惯让他”对代码的每一步变化都心里有数”。有一次他发现分析结果突然不对，通过 Git 历史快速定位到某次提交，发现是那次提交引入了错误。回滚后，问题解决。

扩展记录：2026-04-09 | 目标字数：800+ ### Positron 中的 Git 快捷键

Positron 提供了一系列键盘快捷键，可以显著提高使用 Git 的效率。熟练掌握这些快捷键，可以让你在不用命令行的情况下完成大部分 Git 操作。

必须记住的快捷键

快捷键 功能 说明
Ctrl + Shift + P 打开 Commit 窗口 最常用的操作，提交修改
Ctrl + Shift + G 查看 Diff 查看当前文件的修改内容
Ctrl + P 拉取（Pull） 从远程仓库拉取最新代码
Ctrl + Shift + P 推送（Push） 推送提交到远程仓库

Commit 窗口快捷键

在 Commit 窗口中：

快捷键 功能
Ctrl + R 刷新文件列表
Space 勾选/取消勾选文件
Ctrl + Enter 提交（Commit）
Ctrl + W 关闭 Commit 窗口

Diff 视图快捷键

在 Diff 视图中：

快捷键 功能
↑ / ↓ 上/下一处差异
Ctrl + R 刷新 Diff
Esc 关闭 Diff 视图

自定义快捷键

如果默认快捷键不符合你的习惯，可以在 Positron 中自定义：

  1. Tools → Modify Keyboard Shortcuts
  2. 在搜索框中输入 “Git”
  3. 为你喜欢的操作分配快捷键

生态学案例

某研究生发现，每次提交代码都要用鼠标点击 Git 面板 → 勾选文件 → 点击 Commit，非常繁琐。后来他学会了使用 Ctrl + Shift + P 打开 Commit 窗口，效率提高了一倍。再后来记住了 Ctrl + Shift + P 直接推送，整个提交-推送流程从 2 分钟缩短到 20 秒。

扩展记录：2026-04-09 | 目标字数：800+ ## 常见问题与错误处理

14.1.3 合并冲突（Merge Conflict）

当两个分支修改了同一文件的同一部分时，Git 无法自动合并，会产生合并冲突。这是团队协作中不可避免的问题。

识别冲突

当你在 Positron 中执行 Pull 或 Merge 时，如果出现冲突，Git 会： 1. 在 Git 面板中显示红色图标 2. 在冲突文件中添加标记 3. 在 Console 中显示冲突信息

冲突标记的解读

<<<<<<< HEAD 到 ======= 之间是当前分支的内容，======= 到 >>>>>>> 之间是要合并分支的内容。

解决冲突的步骤

  1. 打开冲突文件，决定保留哪部分内容（或合并两者）
  2. 删除冲突标记 <<<<<<<, =======, >>>>>>>
  3. 保存文件
  4. 在 Git 面板中勾选该文件（git add）
  5. 点击 Commit 完成合并

预防冲突的建议

  • 频繁推送，不要积累大量修改
  • 同一文件让一个人负责
  • 使用功能分支减少直接冲突
  • 推送前先 pull

生态学案例

某小组在提交报告时，3个人同时修改了 report.qmd 的不同部分（引言、方法和讨论）。合并时只有讨论部分产生了冲突。教训是：同一文件的不同部分由不同人负责，可以减少冲突。

扩展记录：2026-04-09 | 目标字数：800+ ### 预防冲突的好习惯

合并冲突虽然可以解决，但预防永远胜于治疗。在团队协作中，养成良好的Git工作习惯可以大幅减少冲突发生的频率和复杂度。以下是经过实践检验的预防策略，特别适用于数据分析项目的协作场景。

核心原则：频繁同步，小步提交

  1. 每次开始工作前先 git pull

    这是最重要的习惯。每天开始工作前、午休后、甚至每次离开电脑超过1小时后，都应该先拉取远程最新代码。这样可以确保你始终在最新的代码基础上工作，避免与队友的修改产生大范围分歧。

    # 每天工作流程
git pull origin main          # 第一步：拉取最新代码
# 开始你的工作...
git add scripts/analysis.R
git commit -m "添加多样性指数计算"
git pull origin main          # 推送前再次拉取（以防队友刚推送了新代码）
git push origin main

  2. 频繁提交、频繁推送，减少冲突范围

    不要等到完成一整天的工作才提交。每完成一个小功能（如完成一个函数、清洗一个变量、绘制一张图）就提交一次。小步提交有两个好处：一是冲突范围小，容易解决；二是即使出错也容易回退到上一个可用版本。

    # 推荐：小步提交
git commit -m "添加缺失值检测函数"        # 提交1
git commit -m "处理pH变量的异常值"       # 提交2
git commit -m "标准化物种名称"           # 提交3

# 不推荐：一次性提交所有修改
git commit -m "完成数据清洗"  # 包含了几十个文件的修改，冲突难以定位

  3. 如果冲突频繁发生，考虑让团队成员各自在不同分支上工作

    当团队规模较大（>3人）或项目复杂度较高时，直接在main分支上协作容易产生频繁冲突。此时应采用分支工作流：每个人在自己的功能分支上工作，完成后再合并到main。

    # 张三负责数据清洗
git checkout -b feature/data-cleaning
# 工作...
git push origin feature/data-cleaning

# 李四负责统计分析
git checkout -b feature/statistical-analysis
# 工作...
git push origin feature/statistical-analysis

# 各自完成后，由项目负责人依次合并到main

  4. 明确分工，避免同时编辑同一文件

    在项目规划阶段就明确每个人负责哪些文件。例如：张三负责01-data-cleaning.R，李四负责02-analysis.R，王五负责03-visualization.R。如果确实需要多人协作同一个文件，可以约定编辑不同的函数或代码块。

  5. 使用代码审查（Code Review）机制

    即使是Collaborator模式，也可以要求成员在推送前先创建Pull Request，由另一位成员审查后再合并。这不仅能减少冲突，还能提高代码质量。

生态学案例：某课题组5人协作分析森林样地数据。初期大家都直接在main分支上工作，结果每天都要解决3-5次合并冲突，严重影响进度。后来采用分支策略：数据清洗组（2人）在dev-cleaning分支工作，分析组（2人）在dev-analysis分支工作，报告撰写（1人）在dev-report分支工作。每周五下午统一合并到main分支，冲突次数减少了80%，项目按时完成。

冲突预警信号：

如果你的团队出现以下情况，说明需要调整协作策略： - 每天解决冲突的时间超过30分钟 - 同一个文件反复出现冲突 - 有人因为害怕冲突而不敢推送代码 - git pull后经常出现几十个文件的冲突

扩展记录：2026-04-09 | 目标字数：800+ :::

14.1.4 常见错误及解决方法

在使用 Git 和 GitHub 时，初学者经常会遇到一些错误。了解这些错误的成因和解决方法，可以帮你快速解决问题。

错误一：push rejected（推送被拒绝）

原因：远程仓库有你本地没有的新提交。

解决方法：先执行 git pull origin main 拉取远程更新，如果有冲突则解决冲突，然后再 git push origin main 推送。

错误二：fatal: not a git repository（不是 Git 仓库）

原因：当前文件夹不是 Git 仓库，或路径不对。

解决方法：检查当前路径和 git status，确保在正确的项目文件夹中。

错误三：fatal: Authentication failed（认证失败）

原因：GitHub 密码错误或 Token 过期。

解决方法：使用 Personal Access Token 代替密码，或在 Windows 凭据管理器中更新 GitHub 凭据。

错误四：nothing to commit, working tree clean（没有可提交的内容）

原因：所有修改已经提交，或者文件没有被 Git 追踪。

解决方法：用 git status 查看文件状态，用 git log –oneline 查看提交历史。

错误五：src refspec main does not match any（分支不存在）

原因：尝试推送时指定的分支名不存在。

解决方法：用 git branch -a 查看所有分支，确保分支名正确。

扩展记录：2026-04-09 | 目标字数：800+ ### git restore 不可撤销

git restore 是一个强大但危险的命令，它会丢弃工作区的修改。由于 Git 不会将丢弃的修改放入”回收站”，所以这个操作不可撤销。

git restore 的作用

# 丢弃工作区的修改（恢复到最近一次提交的状态）
git restore scripts/analysis.R

# 从暂存区移除文件（取消 git add）
git restore --staged scripts/analysis.R

为什么要谨慎使用？

执行 git restore 后，你对文件的所有修改都会消失。没有”撤销”按钮，没有回收站。

安全建议

  1. 使用前确认：在执行 restore 前，用 git diff 查看修改内容
  2. 备份重要修改：如果修改很重要，先用 git stash 暂存
  3. 小步提交：不要积累大量修改再提交，这样即使 restore 也只会丢失少量工作

生态学案例

某研究生在修改数据清洗脚本时，不小心删除了一个重要函数。他慌乱中执行了 git restore data_cleaning.R，结果不仅删掉的函数没恢复，连最近半小时的修改也全部丢失。如果他先用 git diff > backup.patch 备份，就不会丢失工作成果了。

扩展记录：2026-04-09 | 目标字数：800+ ## .gitignore 文件

有些文件不应该被 Git 追踪（如大型数据文件、临时文件、密钥等）。在项目根目录创建 .gitignore 文件：

# R 临时文件
.Rhistory
.RData
.vscode/

# 数据文件（太大不适合放 Git）
data/raw/*.csv
data/raw/*.xlsx

# 系统文件
.DS_Store
Thumbs.db

# 编译产物
docs/
_freeze/
Warning不要把敏感信息提交到 Git

Git 的历史记录是永久的。一旦将敏感信息提交到 Git，就等于公开泄露，即使后来删除文件，历史中仍然保留着内容。

常见的敏感信息

  • API 密钥和密码（如天气 API key、数据库密码）
  • 个人隐私数据（如采样点精确坐标、受试者信息）
  • 证书和密钥文件（如 .pem 文件）
  • 配置文件中包含的密码

如何避免泄露？

  1. 添加到 .gitignore：将敏感文件排除在版本控制之外
# 在 .gitignore 中添加
.env
*.key
data/raw/gps_coordinates.csv

  1. 使用环境变量：将密钥存储在环境变量中，不写入代码

  2. 使用 BFG Repo-Cleaner 重写历史：如果已经提交了敏感信息

生态学案例

某研究团队在 GitHub 上公开了一个仓库，其中包含了一份 GPS 坐标文件。虽然后来删除了这个文件，但有学生下载了仓库的历史版本，通过 commit 历史找到了精确的采样点坐标。这违反了研究伦理，也给后续研究带来了问题。正确的做法是：将坐标数据脱敏后（只保留到村/镇级别）再上传。

扩展记录：2026-04-09 | 目标字数：800+ ## 项目文件组织规范

一个规范的数据分析项目应该有清晰的文件结构：

my-project/
├── README.md           # 项目说明
├── .gitignore          # Git 忽略规则
├── data/
│   ├── raw/            # 原始数据（不修改）
│   └── processed/      # 处理后的数据
├── scripts/
│   ├── 01-clean.R      # 数据清洗
│   ├── 02-analyze.R    # 数据分析
│   └── 03-visualize.R  # 数据可视化
├── output/
│   ├── figures/         # 图表
│   └── tables/          # 表格
└── docs/
    └── report.qmd       # 分析报告

关键原则：

  • 原始数据只读：data/raw/ 中的文件永远不修改
  • 脚本有编号：按执行顺序编号，方便他人复现
  • 输出可重建：output/ 中的所有文件都能通过运行脚本重新生成
  • 有 README：说明项目目的、数据来源、运行方法

14.2 实践：分组创建项目仓库

按照以下步骤完成本章实践（使用 Collaborator 模式）：

  1. 组长在 GitHub 上创建一个新仓库，命名为 ecology-data-project
  2. 添加 README.md 和 .gitignore（选择 R 模板）
  3. 组长在 Settings → Collaborators 中邀请组员
  4. 所有人克隆仓库到本地（使用 Positron）
  5. 按照上面的规范创建文件夹结构
  6. 组长添加一个简单的 R 脚本（如读取 iris 数据并保存描述性统计），提交并推送
  7. 组员先 git pull 拉取最新代码，再各自添加自己的分析脚本，提交推送

14.3 课后练习

  1. 完成 Git 初始配置（user.name 和 user.email）
  2. 在 GitHub 上创建个人项目仓库，包含完整的文件夹结构
  3. 练习 git add → git commit → git push 的完整流程
  4. 查看 git log 确认提交历史
  5. 创建 .gitignore 文件，排除不需要追踪的文件
  6. 尝试在 Positron 中使用 Git 面板完成一次提交和推送
  7. （进阶）与同学协作制造一次合并冲突，练习解决冲突的流程