Golang 使用 Hercules 插件库从 Git 仓库历史获取高级分析洞察

概述

Hercules 是一个用 Go 编写的极快且高度可定制的 Git 仓库分析引擎，由 go-git 提供支持。它包含两个命令行工具：

1. hercules - 用 Go 编写的程序，获取 Git 仓库并在完整提交历史上执行分析任务的有向无环图(DAG)
2. labours - Python 脚本，显示基于收集数据的预定义图表

安装

二进制安装

从 Releases 页面 获取 hercules 二进制文件。

安装 labours:

pip3 install labours

从源码构建

需要 Go (>= v1.11) 和 protoc:

git clone https://github.com/src-d/hercules && cd hercules
make
pip3 install -e ./python

使用示例

基本使用

# 使用内存后端并显示项目燃尽图
hercules --burndown https://github.com/go-git/go-git | labours -m burndown-project --resample month

# 使用文件系统后端并打印仓库基本信息
hercules /path/to/cloned/go-git

# 使用 Protocol Buffers 格式
hercules --burndown --pb https://github.com/git/git /tmp/repo-cache | labours -m burndown-project -f pb --resample raw

高级示例

# 获取线性历史记录，反转后传递给 hercules
git rev-list HEAD | tac | hercules --commits - --burndown https://github.com/git/git | tee cache.yaml | labours -m burndown-project --font-size 16 --backend Agg --output git.png

内置分析功能

项目燃尽图

hercules --burndown
labours -m burndown-project

显示整个仓库的行燃尽统计信息。

文件燃尽图

hercules --burndown --burndown-files
labours -m burndown-file

显示仓库中每个文件的燃尽统计信息。

开发者燃尽图

hercules --burndown --burndown-people [--people-dict=/path/to/identities]
labours -m burndown-person

显示仓库贡献者的燃尽统计信息。

覆盖矩阵

hercules --burndown --burndown-people [--people-dict=/path/to/identities]
labours -m overwrites-matrix

显示开发者之间的代码覆盖关系矩阵。

代码所有权

hercules --burndown --burndown-people [--people-dict=/path/to/identities]
labours -m ownership

显示随时间变化的代码所有权份额。

文件/开发者耦合分析

hercules --couples [--people-dict=/path/to/identities]
labours -m couples -o <name> [--couples-tmp-dir=/tmp]

分析文件和开发者之间的耦合关系。

结构热度分析

hercules --shotness [--shotness-xpath-*]
labours -m shotness

分析代码结构单元的修改频率。

开发者提交序列

hercules --devs [--people-dict=/path/to/identities]
labours -m devs -o <name>

分析开发者的提交时间序列。

新增与修改行数分析

hercules --devs [--people-dict=/path/to/identities]
labours -m old-vs-new -o <name>

分析随时间变化的新增和修改行数。

开发者工作量分析

hercules --devs [--people-dict=/path/to/identities]
labours -m devs-efforts -o <name>

分析开发者的代码修改量。

代码注释情感分析

hercules --sentiment --pb https://github.com/django/django | labours -m sentiment -f pb

分析代码注释的情感倾向。

完整示例

package main

import (
	"gopkg.in/src-d/hercules.v10"
	"gopkg.in/src-d/hercules.v10/leaves"
	"gopkg.in/src-d/hercules.v10/plugins"
)

func main() {
	// 初始化管道
	pipeline := hercules.NewPipeline()
	
	// 配置仓库路径
	repository, err := hercules.LoadRepositoryFromGit("/path/to/repo")
	if err != nil {
		panic(err)
	}
	
	// 设置分析选项
	pipeline.SetRepository(repository)
	pipeline.SetFeaturesFromFlags(
		hercules.FeatureBurndown |
		hercules.FeatureCouples |
		hercules.FeatureShotness)
	
	// 添加燃尽分析
	burndown := leaves.NewBurndownAnalysis()
	burndown.Configure(map[string]interface{}{
		"BurndownGranularity": 30,
		"BurndownSampling":    30,
	})
	pipeline.AddAnalysis(burndown)
	
	// 添加耦合分析
	couples := leaves.NewCouplesAnalysis()
	pipeline.AddAnalysis(couples)
	
	// 添加结构热度分析
	shotness := leaves.NewShotnessAnalysis()
	pipeline.AddAnalysis(shotness)
	
	// 运行分析
	results, err := pipeline.Run()
	if err != nil {
		panic(err)
	}
	
	// 处理结果
	burndownResult := results[burndown].(*leaves.BurndownResult)
	couplesResult := results[couples].(*leaves.CouplesResult)
	shotnessResult := results[shotness].(*leaves.ShotnessResult)
	
	// 这里可以添加自定义结果处理逻辑...
}

缓存机制

# 第一次 - 缓存仓库
hercules https://github.com/git/git /tmp/repo-cache

# 后续使用缓存
hercules --some-analysis /tmp/repo-cache

注意事项

1. 处理所有提交可能会在某些罕见情况下失败
2. 燃尽统计收集可能会因内存不足而失败
3. 当内部对象数量很大时，Python 中的 YAML 解析会很慢
4. 可以通过安装 libyaml 来加速 YAML 解析

路线图

1. 从 src-d/go-git 切换到 go-git/go-git
2. 更新文档
3. 修复报告的错误
4. 移除对 Babelfish 的依赖
5. 移除特定分析功能

Hercules 提供了强大的 Git 仓库历史分析能力，通过组合不同的分析功能，可以获得对代码库演变的深入洞察。