项目概览

本项目围绕 GitHub 仓库/分叉数据采集、入库（MongoDB）、提交历史处理（提交 DAG / 合并 fork）、统计分析（导出 CSV 报表）与 fork 分类（贡献型/二次开发型）展开。

目录结构

• 代码/：主程序与脚本
  • collection/：GitHub 仓库与 forks 采集
  • importers/：CSV/JSONL → MongoDB 导入与合并
  • repo_history/：仓库克隆与提交历史补全
  • dag/：仓库+fork 提交 DAG 构建与入库
  • file_dag/：文件级提交 DAG 库（genere.py）
  • analysis/：统计分析与 fork 分类（含 fork_analysis/）
  • audit/：PR/提交审计与导出
  • validation/：数据验证与研究脚本
• analysis_results.csv：统计结果示例

依赖

• Python 3.9+，Git（命令行），MongoDB（本地：mongodb://localhost:27017/）
• Python 包：pymongo、requests、tqdm、pandas、gitpython

数据流（简化）

1. 采集与导入：collection/ + importers/ → github.repo_with_forks
2. 历史补全：repo_history/ → 本地 selected_repos
3. DAG 构建：dag/ → github.commit_nodes / commit_nodes1
4. 统计分析：analysis/ → analysis_results.csv
5. fork 分类：analysis/fork_analysis/ → 分类 JSON

从 0 到结果（示例）

1. 导入数据（MongoDB）：

cd 代码/importers
export MONGO_URI=mongodb://localhost:27017/
export ORIGINAL_REPOS_CSV=/path/to/top100_repos.csv
export FORKS_CSV=/path/to/top100_forks.csv
python3 data_importer.py

2. 补全提交历史：

cd 代码/repo_history
export SELECTED_REPOS_BASE=/abs/path/selected_repos
python3 git_history_collector.py

3. 构建提交 DAG（批量）：

cd 代码/dag
export SELECTED_REPOS_BASE=/abs/path/selected_repos
python3 commit_tree_analyzer.py

4. 导出统计：

cd 代码/analysis
export ANALYSIS_CSV=analysis_results.csv
python3 final_analyzer.py

5. 查看示例输出：

ls examples/analysis_results.csv

6. 导出 PR 汇总（最新步骤）：

cd 代码/audit
export PR_SUMMARY_CSV=repo_pr_commit_summary.csv
python3 repo_pr_commit_summary.py

快速开始

1. 导入数据：进入 importers/ 运行相应脚本
2. 克隆历史：进入 repo_history/ 运行 git_history_collector.py
3. 构建 DAG：进入 dag/ 运行 commit_tree_analyzer.py
4. 导出统计：进入 analysis/ 运行 final_analyzer.py
5. fork 分类：进入 analysis/fork_analysis/ 运行相关脚本

环境与配置

• 复制 .env.example 为 .env 并按需修改；或直接设置环境变量：
  • GITHUB_TOKENS、GITHUB_TOKEN（二选一/按需）
  • SELECTED_REPOS_BASE、MONGO_URI 等

GitHub 仓库

• 本项目已移除硬编码 Token 和绝对路径；可直接推送到 GitHub。
• 提交前请确保 .env 与缓存/大文件未纳入版本控制（见 .gitignore）。

---

模块详解（目录 → 作用）

• 代码/collection/：调用 GitHub API 抓取 Top 仓库与 forks（支持多 Token 轮换，断点续抓，带缓存）。
• 代码/importers/：将 CSV/JSONL 导入 MongoDB，并做 repos/forks 到 repo_with_forks 的合并。
• 代码/repo_history/：按 SELECTED_REPOS_BASE 浅克隆仓库并 --unshallow 补齐完整提交历史，带失败重试与标记文件。
• 代码/dag/：按仓库及其 forks 构建提交 DAG，写入 commit_nodes/commit_nodes1（分片入库）。
• 代码/file_dag/：genere.py 提供文件级精简 DAG 构建与 Mongo 持久化的库函数（按目录/文件层级组织节点）。
• 代码/analysis/：统计分析脚本，汇总并导出 analysis_results.csv 到 examples/。
• 代码/audit/：PR/提交审计脚本（从 pr_commit_data 拉取，调用 GitHub API 获取 stats/files，导出 CSV 或写回集合）。
• 代码/validation/：研究/核验脚本（时间模式、寿命、贡献统计等），不参与主线上批量流程。

环境变量一览（常用）

• GITHUB_TOKENS：逗号分隔的多个 GitHub Token（抓取/审计脚本用）。
• MONGO_URI：Mongo 连接串（默认 mongodb://localhost:27017/）。
• SELECTED_REPOS_BASE：本地完整仓库根目录（用于历史补全、DAG 构建）。
• ORIGINAL_REPOS_CSV / FORKS_CSV：导入脚本输入路径（importers/）。
• PR_COMMIT_CSV / PR_COMMIT_OUTPUT：PR 提交数据的输入/输出（按需）。
• ANALYSIS_CSV：分析结果导出文件名（默认 analysis_results.csv）。

可选（file_dag/genere.py）：

• GIT_GRAPH_MONGO_URI / GIT_GRAPH_MONGO_DB / GIT_GRAPH_MONGO_COLL：文件级 DAG 持久化目标库/表。
• GIT_GRAPH_CLEAR_FIRST、GIT_GRAPH_FOLLOW_RENAMES、GIT_GRAPH_SINCE、GIT_GRAPH_INCLUDE：细节控制。

MongoDB 集合与索引（建议）

• github.repo_with_forks：原始仓与其 forks 的合并文档。
• github.commit_nodes / github.commit_nodes1：提交 DAG（可能按 repo 分片）。
• github.pr_commit_data：PR 与提交的原始明细。
• github.pr_commit_with_stats / github.new_pr_commit_with_stats：含 stats/files 的增强明细（按所用脚本而定）。

建议索引（提升联表/查询性能）：

• repo_with_forks.repo_id（唯一/普通）、repo_with_forks.forks.repo_id（子文档查询）
• commit_nodes(1).repo、commit_nodes(1).commits.<SHA>（按需要）
• pr_commit_data.Repo、pr_commit_data.PR Number

更多示例

文件级 DAG（单仓库）持久化示例：

cd 代码/file_dag
export SELECTED_REPOS_BASE=/abs/path/selected_repos
python3 genere.py owner/repo

PR 提交增强并导出（含文件更改明细）：

cd 代码/audit
export GITHUB_TOKENS=tok1,tok2
python3 pr_commit_files_enricher.py

故障排查 FAQ

• GitHub 403 / 速率限制：配置多个 GITHUB_TOKENS 并自动轮换；适当添加 sleep。
• Push 被拦截（Push Protection）：从代码/提交历史中移除密钥，git commit --amend 然后 git push --force。
• Mongo 连接失败：确认 MONGO_URI、本地服务状态与网络可达。
• 本地仓库路径不存在：检查 SELECTED_REPOS_BASE 与 selected_repos 实际目录结构。
• 大仓库克隆超时：提高超时时间、减少并发、重试，或分批处理。