Git版本控制：项目管理全流程

生信项目的脚本经常经历多次修改——调参数、换软件版本、修 bug。没有版本控制时，目录里满是 analysis_v1.sh、analysis_v2_fixed_final.sh，三个月后很难追溯哪个版本产出了哪些结果。

Git 在生信中的价值常被低估。核心问题：分析结果能复现吗？三个月前的代码还能跑吗？协作时参数变更可追溯吗？本文覆盖 Git 全流程：初始化、分支策略、.gitignore 配置、大文件处理、版本回退、协*生信项目里 Git 的实际用法**，重点是防坑和提效，不是 Git 语法手册。

实测环境：Debian 12，Git 2.45.2。

1. 初始化——生信项目的第一步#

1.1 从零开始#

1
# 创建项目目录并初始化 Git
2
mkdir rnaseq-brca-analysis
3
cd rnaseq-brca-analysis
4
git init
5

6
# 查看状态
7
git status

1.2 立即创建 .gitignore#

生信项目里 .gitignore 比代码还重要——否则一个 git add . 会把几十 GB 的 FASTQ 和 BAM 文件全部纳入版本控制。

1
# .gitignore —— 生信项目标准模板
2
cat > .gitignore << 'EOF'
3
# === 数据文件（太大，不纳入版本控制） ===
4
*.fastq
5
*.fastq.gz
6
*.fq
7
*.fq.gz
8
*.bam
9
*.bai
10
*.sam
11
*.cram
12
*.vcf
13
*.vcf.gz
14
*.bcf
15
*.bigwig
16
*.bw
17
*.bedgraph
18

19
# === 参考基因组和索引（从特定路径引用，不复制） ===
20
*.fa
21
*.fa.gz
22
*.fa.fai
23
*.dict
24
*.mmi
25
*.bwt
26
*.pac
27
*.sa
28
*.ann
29
*.amb
30
*.ht2
31
*.bt2
32

33
# === 中间结果 ===
34
tmp/
35
temp/
36
*.tmp
37
*.log
38
*.o
39
*.e
40
work/
41
.nextflow/
42
.nextflow.log*
43

44
# === Python ===
45
__pycache__/
46
*.py[cod]
47
*.so
48
*.egg-info/
49
.eggs/
50
dist/
51
build/
52
*.whl
53

54
# === R ===
55
.Rproj.user/
56
.Rhistory
57
.RData
58
.Ruserdata
59
*.Rproj
60

61
# === Conda ===
62
conda_env/
63
envs/
64

65
# === 编辑器/IDE ===
66
.vscode/
67
.idea/
68
*.swp
69
*.swo
70
*~
71
.DS_Store
72

73
# === 敏感信息 ===
74
.env
75
*.key
76
*.token
77
config.local.sh
78

79
# === Jupyter ===
80
.ipynb_checkpoints/
81

82
# === 系统文件 ===
83
Thumbs.db
84
Desktop.ini
85
EOF

每个生信项目都应该根据实际需求调整 .gitignore。

1.3 初始提交#

1
git add .gitignore
2
git commit -m "chore: initialize project with .gitignore"
3

4
# 添加项目骨架
5
mkdir -p scripts data results docs logs config
6
git add scripts/ docs/ config/
7
git commit -m "feat: add project directory structure"

2. 分支策略——一个人 vs 团队的用法#

2.1 单人项目（简单模式）#

1
# 直接在 main 上工作也行，但建议至少分两个分支
2
# main: 稳定版本
3
# dev:  开发中的代码
4

5
git checkout -b dev
6

7
# 在 dev 上做分析开发...
8
git add scripts/deseq2_analysis.R
9
git commit -m "feat: add DESeq2 differential expression analysis"
10

11
# 跑通了，合并回 main
12
git checkout main
13
git merge dev
14
git tag -a "v1.0.0" -m "First complete analysis: BRCA tumor vs normal"

2.2 团队协作（推荐 Git Flow 简化版）#

1
# main:       生产就绪代码
2
# dev:        开发主线
3
# feature/*:  新特性分支
4
# hotfix/*:   紧急修复分支
5
# release/*:  发布准备分支
6

7
# 开始一个新分析
8
git checkout -b feature/gsea-analysis dev
9

10
# 开发完成
11
git checkout dev
12
git merge feature/gsea-analysis
13
git branch -d feature/gsea-analysis
14

15
# 发布版本
16
git checkout -b release/v2.0 main
17
# 在 release 分支上做最后测试和微调
18
git checkout main
19
git merge release/v2.0
20
git tag -a "v2.0.0" -m "Release v2.0: Added GSEA pathway analysis"

2.3 生信特有的分支场景#

1
# 参数探索分支——尝试不同参数组合
2
git checkout -b exp/deseq2-lfcShrink-vs-normal
3
# ...试完了，如果效果好就合并，否则直接删掉
4

5
# 数据子集分支——分析不同 cohort
6
git checkout -b analysis/tcga-cohort
7
git checkout -b analysis/gtex-cohort

3. 提交信息规范——三个月后还能看懂#

生信项目建议使用约定式提交（Conventional Commits）：

1
# 格式：<type>: <简短描述>
2

3
# 好的提交信息
4
git commit -m "feat: add STAR alignment script with 2-pass mode"
5
git commit -m "fix: correct strand-specific parameter in featureCounts"
6
git commit -m "refactor: extract QC functions into separate R script"
7
git commit -m "docs: add pipeline usage instructions to README"
8
git commit -m "data: update sample metadata with new clinical info"
9
git commit -m "perf: parallelize DESeq2 with BiocParallel (8 cores)"
10

11
# 避免这种提交信息
12
git commit -m "update"
13
git commit -m "fix bug"
14
git commit -m "asdfghjkl"

类型速查：

type	用途	生信例子
`feat`	新功能/新分析	新增差异表达分析脚本
`fix`	修bug	修复样本配对逻辑错误
`refactor`	重构代码	提取公共函数到 utils.R
`docs`	文档	更新 README 使用说明
`data`	元数据变更	更新样本分组信息
`perf`	性能优化	多线程并行提速
`chore`	杂项	更新 .gitignore

4. 大文件处理——生信的核心痛点#

4.1 Git 不适合存大文件#

Git 的设计目标是文本源码，不是二进制大文件。一个 1GB 的 BAM 文件提交进去，整个仓库就成了灾难。GitHub 单文件限制 100MB，超过就会拒绝 push。生信数据文件动辄几十 GB，该怎么管？

4.2 Git LFS——大文件版本控制#

1
# 安装 Git LFS
2
sudo apt install git-lfs -y
3
git lfs install
4

5
# 追踪特定文件类型
6
git lfs track "*.bam"
7
git lfs track "*.fastq.gz"
8
git lfs track "data/genome/*.fa"
9

10
# .gitattributes 会自动生成
11
# 然后正常 add/commit/push
12
git add data/genome/Homo_sapiens.GRCh38.dna.primary_assembly.fa
13
git commit -m "data: add reference genome (tracked by LFS)"

但我的建议是：能不用 LFS 就不用。 参考基因组和大数据文件应该通过绝对路径引用或脚本下载，而不是塞进 Git。

1
# 更好的做法：脚本化数据获取
2
#!/bin/bash
3
set -euo pipefail
4
REF_DIR="${1:-/opt/refs/hg38}"
5
mkdir -p "${REF_DIR}"
6
cd "${REF_DIR}"
7
wget -c ftp://ftp.ensembl.org/pub/release-113/fasta/homo_sapiens/dna/Homo_sapiens.GRCh38.dna.primary_assembly.fa.gz
8
gunzip Homo_sapiens.GRCh38.dna.primary_assembly.fa.gz
9
echo "Reference downloaded to ${REF_DIR}"

5. 版本回退——救命操作#

5.1 查看历史#

1
# 简洁的提交历史
2
git log --oneline --graph --decorate -20
3

4
# 查看某个文件的历史
5
git log -p scripts/deseq2_analysis.R
6

7
# 查看某次提交改了什么
8
git show a1b2c3d
9

10
# 查看谁改了什么（blame）
11
git blame scripts/utils.R

5.2 撤销操作#

1
# 1. 撤销工作区的修改（还没 add）
2
git checkout -- scripts/broken_analysis.R
3

4
# 2. 撤销暂存区的修改（已经 add，还没 commit）
5
git reset HEAD scripts/broken_analysis.R
6
git checkout -- scripts/broken_analysis.R
7

8
# 3. 撤销最近一次提交（保留修改）
9
git reset --soft HEAD~1
10

11
# 4. 撤销最近一次提交（丢弃修改，危险！）
12
git reset --hard HEAD~1
13

14
# 5. 创建一个新提交来"撤销"旧提交（安全，推荐）
15
git revert a1b2c3d
16

17
# 6. 回到历史某个版本看看（不修改分支）
18
git checkout a1b2c3d
19
# 看完后回来：
20
git checkout main

5.3 救命稻草——git reflog#

1
# 即使 reset --hard 后也能找回
2
git reflog
3
# a1b2c3d HEAD@{0}: reset: moving to HEAD~1
4
# d4e5f6g HEAD@{1}: commit: feat: add important analysis
5
# ...
6

7
# 恢复到误删之前的提交
8
git reset --hard d4e5f6g

reflog 是我最感谢 Git 的功能。 生信里经常试验性地改参数，改完发现不对想回去，reflog 就是时光机。

6. 与远程仓库协作#

1
# 关联 GitHub/GitLab/Gitee
2
git remote add origin git@github.com:username/rnaseq-brca-analysis.git
3

4
# 首次推送
5
git push -u origin main
6

7
# 日常推送
8
git add scripts/
9
git commit -m "feat: add GSEA visualization"
10
git push
11

12
# 拉取协作者的更新
13
git pull origin main
14

15
# 处理冲突
16
git pull origin main
17
# CONFLICT (content): Merge conflict in scripts/utils.R
18
# 手动编辑冲突文件，然后：
19
git add scripts/utils.R
20
git commit -m "merge: resolve conflict in utils.R"

7. 踩坑记录#

坑1：把大文件提交了。 即使后来从 .gitignore 排除了，Git 历史里仍然存着这个文件。解决方法：git filter-branch 或 git filter-repo 从历史中彻底清除。在 git add 之前检查 git status，一旦发现大文件立刻撤销。

坑2：Windows 和 Linux 换行符冲突。 Windows 用 \r\n，Linux 用 \n。Git 默认可能自动转换换行符，导致 Shell 脚本在 Linux 上无法执行。在项目根目录创建 .gitattributes：

1
* text=auto
2
*.sh text eol=lf
3
*.R text eol=lf
4
*.py text eol=lf

坑3：git pull 产生不必要的合并提交。 用 git pull --rebase 代替默认的 merge，保持历史线性。或者全局设置：git config --global pull.rebase true。

坑4：分支命名混乱导致找不到代码。 统一命名规范：feature/描述、fix/描述、analysis/描述。每完成一个分析就打 tag：git tag -a "analysis/deseq2-v1" -m "DESeq2 results for manuscript Fig2"。

坑5：敏感信息提交到了公开仓库。 密码、API Key、Token 一旦 push 到 GitHub 就永久留在历史里。永远不要硬编码凭据，用环境变量或 .env 文件（加到 .gitignore）。如果已经泄露，立即 revoke token 并用 git filter-repo 清除。

坑6：直接在 main 分支上做实验性分析。 分析跑了两周发现方向错了，但 main 分支已经被改得面目全非。新分析一定开新分支，即使只是一个人。

坑7：忘记写 .gitignore 导致 data 目录被跟踪。 运行一次 git rm -r --cached data/ 可以从 Git 跟踪中移除但保留本地文件，然后更新 .gitignore 并提交。

本文于 2025-07-03 在 Debian 12 上实测。