# rvcommit-scanner

**Repository Path**: rvsmart-porting/rvcommit-scanner

## Basic Information

- **Project Name**: rvcommit-scanner
- **Description**: 面向Git仓库的RV相关commit扫描工具
- **Primary Language**: Python
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2025-04-30
- **Last Updated**: 2025-10-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# RVCommit Scanner

<div align="center">

[![Python Version](https://img.shields.io/badge/python-3.7+-blue.svg)](https://python.org)
[![License](https://img.shields.io/badge/license-GPL--3.0-blue.svg)](LICENSE)

面向Git仓库的RISC-V相关commit扫描工具

[English](README.en.md) | 中文

</div>

## 📖 项目介绍

RVCommit Scanner 是一个专门用于扫描Git仓库中RISC-V架构相关提交的工具。软件项目通常统一维护特定于各种指令集架构的代码，各架构特定的代码及其修改都在相同的Git仓库中完成。本项目旨在建立智能匹配规则，根据规则扫描Git仓库，提取RISC-V架构相关的commit，并对commit数据进行多视角的处理和可视化呈现。

### 🎯 核心功能

- **智能关键词匹配**: 使用正则表达式匹配RISC-V相关关键词（rv32、rv64、risc-v等）
- **提交历史扫描**: 深度扫描Git仓库的提交历史，识别RISC-V相关修改
- **远程仓库支持**: 支持直接扫描GitHub、GitLab等远程仓库（HTTP/HTTPS/SSH）
- **多种输出格式**: 支持控制台输出、JSON文件导出、Web界面展示
- **数据可视化**: 提供Web界面进行交互式数据展示和分析
- **灵活的扫描控制**: 支持限制扫描数量、只显示匹配项、首次匹配即停止等选项

## 🚀 快速开始

### 环境要求

- Python 3.7+
- Git

### 安装方式

```bash
git clone https://github.com/yourusername/rvcommit-scanner.git
cd rvcommit-scanner
pip install -e .
```

#### 验证安装

安装完成后，验证命令是否可用：

```bash
# 检查RISC-V扫描器
rvcommit-scanner help

# 检查通用Git扫描器
git-scan --help
```

### 基本用法

#### RISC-V专用扫描器 (rvcommit-scanner)

**扫描RISC-V相关提交：**
```bash
# 扫描当前目录
rvcommit-scanner scan

# 扫描指定目录
rvcommit-scanner scan /path/to/your/git/repo

# 扫描GitHub仓库
rvcommit-scanner scan https://github.com/user/repo.git

# 扫描SSH仓库
rvcommit-scanner scan git@github.com:user/repo.git

# 保存为JSON文件
rvcommit-scanner scan /path/to/repo --output results.json
```

**启动Web界面：**
```bash
# 扫描后自动启动Web服务器
rvcommit-scanner scan /path/to/repo --web

# 指定端口
rvcommit-scanner scan /path/to/repo --web --port 9000

# 单独启动Web服务器
rvcommit-scanner web --port 8080

# 显示已有的扫描结果
rvcommit-scanner web --data results.json --port 8080
```

**获取帮助信息：**
```bash
# 显示主帮助
rvcommit-scanner help

# 显示scan命令帮助
rvcommit-scanner help scan

# 显示web命令帮助
rvcommit-scanner help web
```

#### Git Commit Scanner (通用工具)

通用的Git提交扫描工具，支持自定义关键词：

```bash
# 基本用法：扫描特定关键词
git-scan /path/to/repo "keyword"

# 使用正则表达式
git-scan /path/to/repo "rv(32|64)" --regex

# 限制扫描数量
git-scan /path/to/repo "risc-v" --limit 100
```

## 📊 功能特性

### 🔍 智能扫描引擎

- **关键词匹配**: 内置RISC-V相关关键词模式
  - `rv32`, `rv64`, `rv128`
  - `risc-v`, `riscv`, `risc_v`
  - 支持大小写不敏感匹配
- **文件过滤**: 自动排除锁文件和无关文件
- **正则表达式**: 支持复杂的模式匹配

### 🌐 Web可视化界面

- **现代化UI**: 基于Tailwind CSS的响应式设计
- **交互式图表**: 使用Chart.js进行数据可视化
- **多维度分析**: 
  - 提交时间线分析
  - 文件影响热力图
  - 贡献者统计
  - 关键词频率分析
- **国际化**: 中英文界面切换

### 📈 数据分析

- **提交统计**: 按时间、作者、文件类型统计
- **影响分析**: 分析代码变更的影响范围
- **趋势分析**: RISC-V相关开发活动的时间趋势
- **导出功能**: JSON格式的详细扫描报告

## 📁 项目结构

```
rvcommit-scanner/
├── git_commit_scanner/          # 通用Git提交扫描器
│   ├── __init__.py
│   ├── cli.py                   # 命令行接口
│   └── scanner.py               # 核心扫描逻辑
├── rvcommit_scanner/            # RISC-V专用扫描器
│   ├── __init__.py
│   ├── cli.py                   # 主命令行接口
│   ├── rv_keyword_scanner.py    # RISC-V关键词扫描器
│   └── html/                    # Web界面资源
│       ├── index.html           # 主页面
│       ├── styles.css           # 样式文件
│       └── js/                  # JavaScript文件
├── test/                        # 测试文件和数据
├── requirements.txt             # Python依赖
├── setup.py                    # 安装配置
└── README.md                   # 项目文档
```

## 🔧 配置选项

### 命令行选项参考

#### rvcommit-scanner scan 命令选项

| 选项 | 短选项 | 类型 | 默认值 | 说明 |
|------|--------|------|---------|------|
| `--limit` | `-n` | 整数 | 无限制 | 限制扫描的提交数量 |
| `--only-matched` | `-m` | 标志 | False | 只显示匹配RISC-V关键词的提交 |
| `--only-once` | `--once` | 标志 | False | 找到第一个匹配后停止扫描 |
| `--output` | `-o` | 路径 | 无 | 指定JSON结果输出文件 |
| `--web` | `-w` | 标志 | False | 扫描后启动Web服务器 |
| `--port` | `-p` | 整数 | 8080 | Web服务器端口号 |
| `--fast-mode` | `-f` | 标志 | False | 启用快速扫描模式，跳过某些检查 |

#### rvcommit-scanner web 命令选项

| 选项 | 短选项 | 类型 | 默认值 | 说明 |
|------|--------|------|---------|------|
| `--port` | `-p` | 整数 | 8080 | Web服务器端口号 |
| `--data` | `-i` | 路径 | 无 | 显示的JSON数据文件 |

#### git-scan 命令选项

| 选项 | 短选项 | 类型 | 默认值 | 说明 |
|------|--------|------|---------|------|
| `--regex` | `-r` | 标志 | False | 启用正则表达式匹配 |
| `--exclude` | `-e` | 字符串 | 无 | 排除指定文件或目录（正则表达式） |
| `--type` | `-t` | 字符串 | all | 限制扫描的对象类型（all, commit, file, msg） |
| `--limit` | `-n` | 整数 | 无限制 | 限制扫描的提交数量 |
| `--only-matched` | `-m` | 标志 | False | 只显示匹配关键词的提交 |

### 扫描配置

可以通过修改 `rvcommit_scanner/rv_keyword_scanner.py` 中的关键词模式来自定义扫描规则：

```python
common_rv_keywords = [
    ScanPattern(r"(?i)(?<![a-z0-9])rv(32|64|128)(?![0-9])", True),
    ScanPattern(r"(?i)risc[\s_-]?v", True),
]
```

### 排除文件

默认排除以下类型的文件：
- 包管理器锁文件 (`package-lock.json`, `Cargo.lock` 等)
- 隐藏文件 (以`.`开头的文件)
- 文档文件 (如 `.md` 等)
- 二进制文件

## 🚀 性能优化

### 扫描大型仓库的最佳实践

1. **使用限制选项**：对于大型仓库，使用 `--limit` 限制扫描数量
2. **远程仓库优化**：工具会自动根据 `--limit` 值优化克隆深度
3. **使用 `--only-matched`**：只显示匹配的提交，减少输出
4. **使用 `--once`**：如果只需要找到第一个匹配，可以快速停止

```bash
# 优化示例：快速扫描大型仓库的最近1000个提交
rvcommit-scanner scan https://github.com/torvalds/linux.git --limit 1000 --only-matched
```

## 🐛 故障排除

### 常见问题及解决方案

**1. 远程仓库克隆失败**
```bash
Error cloning repository: ...
```
解决方案：
- 检查URL是否正确
- 对于SSH URL，确保SSH密钥已配置
- 检查网络连接
- 尝试使用HTTPS URL替代SSH

**2. "Path does not exist" 错误**
```bash
Error: Path '/path/to/repo' does not exist.
```
解决方案：
- 确保路径正确
- 确保目录是Git仓库
- 使用绝对路径

**3. Web服务器端口被占用**
```bash
OSError: [Errno 48] Address already in use
```
解决方案：
- 使用不同端口：`--port 9000`
- 停止占用端口的程序
- 检查端口使用情况：`lsof -i :8080`

**4. 扫描结果为空**
可能原因：
- 仓库中没有RISC-V相关提交
- 关键词匹配规则过于严格
- 使用了 `--limit` 但匹配项在更早的提交中

解决方案：
- 增加 `--limit` 值
- 移除 `--only-matched` 选项查看所有扫描的提交
- 检查仓库是否包含相关内容

**5. JSON输出文件无法创建**
解决方案：
- 检查输出路径的写权限
- 确保输出目录存在
- 使用绝对路径

## 📜 许可证

本项目采用 GPL-3.0 许可证 - 查看 [LICENSE](LICENSE) 文件了解详细信息。

## 🤝 贡献者

- **jxzhu** - 初始工作
- **Hein** - 核心开发和维护

## 🔗 相关链接

- [RISC-V International](https://riscv.org/)
- [Git官方文档](https://git-scm.com/doc)
- [Python GitPython](https://gitpython.readthedocs.io/)