827. 代码/数据版本控制：Git vs DVC¶

一句话概述：Git管代码版本，DVC管数据版本——两者配合使用，让生信分析真正做到"完全可重复"。

核心知识点速查表¶

维度	Git	DVC (Data Version Control)
管理对象	代码、配置文件、小文件	大数据文件、模型、结果
文件大小限制	建议<100MB	无限制（GB/TB级）
存储方式	本地.git目录	远程存储(S3/GCS/SSH)
版本追踪	文件内容差异(diff)	文件哈希值(.dvc文件)
平台	GitHub/GitLab/Gitee	配合Git使用
适用场景	脚本、Snakefile、README	FASTQ、BAM、参考基因组

一、为什么生信需要数据版本控制？（白话版）¶

你的分析流程依赖： - 脚本代码（几KB）→ Git完美管理 - 参考基因组（3GB）→ Git装不下 - 原始测序数据（50GB）→ Git会崩溃 - 中间结果BAM（20GB）→ Git不可能

DVC = "给大文件用的Git"。它不把大文件存到Git仓库里，而是存到远程服务器(S3、NAS等)，只在Git里记一个"小指纹文件"(.dvc)。

二、Git基础操作（生信必会）¶

# 初始化Git仓库
git init                               # 在当前目录创建Git仓库
git clone https://github.com/user/repo.git  # 克隆远程仓库

# 日常工作流
git add scripts/run_analysis.sh        # 暂存修改的文件
git commit -m "feat: 添加比对脚本"      # 提交到本地仓库
git push origin main                   # 推送到远程仓库

# 分支管理
git branch feature-new-filter          # 创建新分支
git checkout feature-new-filter        # 切换分支
git merge feature-new-filter           # 合并分支到当前分支

# 查看历史
git log --oneline                      # 简洁查看提交历史
git diff HEAD~1                        # 查看与上次提交的差异
git blame scripts/filter.py            # 查看每行的修改者

# .gitignore —— 告诉Git忽略这些文件
cat .gitignore
# *.fastq.gz                           # 忽略FASTQ文件
# *.bam                                # 忽略BAM文件
# *.bai                                # 忽略BAM索引
# results/                             # 忽略结果目录
# .snakemake/                          # 忽略Snakemake缓存

三、DVC数据版本控制¶

# 安装DVC
pip install dvc                        # 安装DVC核心
pip install dvc-s3                     # S3远程存储支持
pip install dvc-ssh                    # SSH远程存储支持

# 初始化DVC（在Git仓库中）
cd my_project                          # 进入项目目录
dvc init                               # 初始化DVC（会创建.dvc/目录）

# 添加大文件到DVC追踪
dvc add data/raw/sample1.fastq.gz      # DVC追踪大文件
# 执行后产生：
# data/raw/sample1.fastq.gz.dvc        # 指纹文件（记录哈希值）
# data/raw/.gitignore                  # 自动让Git忽略大文件

# 将指纹文件提交到Git
git add data/raw/sample1.fastq.gz.dvc  # 暂存.dvc指纹文件
git add data/raw/.gitignore            # 暂存.gitignore
git commit -m "data: 添加样本1原始数据" # 提交到Git

# 配置远程存储
dvc remote add -d myremote \           # 添加默认(-d)远程存储
  ssh://server:/data/dvc-storage       # SSH远程存储路径
# 或者用S3：
# dvc remote add -d myremote s3://bucket/dvc-storage

# 推送数据到远程
dvc push                               # 推送所有DVC追踪的文件

# 拉取数据（其他人/其他机器）
git clone https://github.com/user/my_project.git  # 克隆代码
cd my_project
dvc pull                               # 下载所有大数据文件

四、典型生信项目结构¶

my_metagenome_project/
├── .git/                              # Git版本控制目录
├── .dvc/                              # DVC配置目录
│   └── config                         # 远程存储配置
├── data/
│   ├── raw/
│   │   ├── sample1.fastq.gz           # 大文件（DVC追踪）
│   │   ├── sample1.fastq.gz.dvc       # DVC指纹文件（Git追踪）
│   │   └── .gitignore                 # Git忽略大文件
│   └── reference/
│       ├── genome.fa                  # 参考基因组（DVC追踪）
│       └── genome.fa.dvc              # 指纹文件
├── scripts/
│   ├── 01_qc.sh                       # 质控脚本（Git追踪）
│   ├── 02_assembly.sh                 # 组装脚本（Git追踪）
│   └── 03_binning.py                  # 分箱脚本（Git追踪）
├── Snakefile                          # 流程定义（Git追踪）
├── environment.yml                    # conda环境（Git追踪）
└── README.md                          # 说明文档（Git追踪）

五、DVC Pipeline（流程追踪）¶

# DVC还能追踪分析流程（类似简化版Snakemake）
dvc run -n quality_control \           # 阶段名称
  -d data/raw/sample1.fastq.gz \       # 依赖文件
  -d scripts/01_qc.sh \               # 依赖脚本
  -o results/qc/ \                     # 输出目录
  bash scripts/01_qc.sh               # 执行命令

# 重现流程
dvc repro                              # 重新执行所有变更的阶段

# 查看流程DAG
dvc dag                                # 显示依赖关系图

六、面试高频问题¶

Q: 为什么不把大文件直接放Git？ A: Git设计用于文本文件差异追踪，大二进制文件会导致仓库膨胀、clone极慢。10GB的BAM文件每改一次Git就存一份完整副本。
Q: Git LFS和DVC有什么区别？ A: Git LFS依赖特定的Git服务器支持（GitHub LFS有容量和带宽限制），DVC支持任意存储后端（S3、SSH、NAS）更灵活。
Q: 如何让合作者重现你的分析？ A: Git管代码+Snakefile+环境配置，DVC管数据，Docker/Singularity管软件环境。三者结合=完全可重复。

常见报错与解决¶

报错	原因	解决
`fatal: this exceeds GitHub's file size limit`	文件>100MB推送GitHub	用DVC追踪大文件
`ERROR: failed to push` (DVC)	远程存储配置错误	`dvc remote list`检查配置
`ERROR: output already tracked by SCM`	文件同时被Git和DVC追踪	`git rm --cached file`后再`dvc add`
`merge conflict` (Git)	多人修改同一文件	手动解决冲突后`git add`+`git commit`
`.dvc文件冲突`	多人修改同一数据	协商谁的版本为准，`dvc checkout`

速查表¶

# Git 速查
git init / clone / add / commit / push / pull
git branch / checkout / merge / rebase
git log --oneline / diff / blame / stash
git tag v1.0                    # 打标签

# DVC 速查
dvc init                        # 初始化
dvc add large_file              # 追踪大文件
dvc push / pull                 # 推送/拉取数据
dvc remote add -d name path     # 配置远程存储
dvc run -n name -d dep -o out   # 定义流程阶段
dvc repro                       # 重现流程
dvc dag                         # 查看依赖图
dvc diff                        # 查看数据变更