# rvcommit-scanner

**Repository Path**: HeinUmin/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**: 0
- **Forks**: 1
- **Created**: 2025-07-06
- **Last Updated**: 2025-09-28

## 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)

RISC-V related commit scanner for Git repositories

English | [中文](README.md)

</div>

## 📖 Project Introduction

RVCommit Scanner is a specialized tool for scanning RISC-V architecture-related commits in Git repositories. Software projects typically maintain code specific to various instruction set architectures in a unified manner, with architecture-specific code and modifications all completed within the same Git repository. This project aims to establish intelligent matching rules to scan Git repositories according to these rules, extract RISC-V architecture-related commits, and provide multi-perspective processing and visualization of commit data.

### 🎯 Core Features

- **Smart Keyword Matching**: Uses regular expressions to match RISC-V related keywords (rv32, rv64, risc-v, etc.)
- **Commit History Scanning**: Deep scanning of Git repository commit history to identify RISC-V related changes
- **Remote Repository Support**: Supports direct scanning of remote repositories from GitHub, GitLab, etc. (HTTP/HTTPS/SSH)
- **Multiple Output Formats**: Supports console output, JSON file export, and web interface display
- **Data Visualization**: Provides web interface for interactive data display and analysis
- **Flexible Scan Control**: Supports limiting scan count, showing only matches, stopping after first match, etc.

## 🚀 Quick Start

### Requirements

- Python 3.7+
- Git

### Installation

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

#### Installation Verification

After installation, verify the commands are available:

```bash
# Check RISC-V scanner
rvcommit-scanner help

# Check general Git scanner
git-scan --help
```

### Basic Usage

#### RISC-V Specialized Scanner (rvcommit-scanner)

**Scanning RISC-V Related Commits:**
```bash
# Scan current directory
rvcommit-scanner scan

# Scan specified directory
rvcommit-scanner scan /path/to/your/git/repo

# Scan GitHub repository
rvcommit-scanner scan https://github.com/user/repo.git

# Scan SSH repository
rvcommit-scanner scan git@github.com:user/repo.git

# Save as JSON file
rvcommit-scanner scan /path/to/repo --output results.json
```

**Launch Web Interface:**
```bash
# Scan and automatically start web server
rvcommit-scanner scan /path/to/repo --web

# Specify port
rvcommit-scanner scan /path/to/repo --web --port 9000

# Start web server separately
rvcommit-scanner web --port 8080

# Display existing scan results
rvcommit-scanner web --data results.json --port 8080
```

**Get Help Information:**
```bash
# Show main help
rvcommit-scanner help

# Show scan command help
rvcommit-scanner help scan

# Show web command help
rvcommit-scanner help web
```

#### Git Commit Scanner (General Tool)

General Git commit scanning tool supporting custom keywords:

```bash
# Basic usage: scan for specific keyword
git-scan /path/to/repo "keyword"

# Use regular expressions
git-scan /path/to/repo "rv(32|64)" --regex

# Limit scan count
git-scan /path/to/repo "risc-v" --limit 100
```

## 📊 Feature Details

### 🔍 Smart Scanning Engine

- **Keyword Matching**: Built-in RISC-V related keyword patterns
  - `rv32`, `rv64`, `rv128`
  - `risc-v`, `riscv`, `risc_v`
  - Case-insensitive matching support
- **File Filtering**: Automatically excludes lock files and irrelevant files
- **Regular Expressions**: Supports complex pattern matching

### 🌐 Web Visualization Interface

- **Modern UI**: Responsive design based on Tailwind CSS
- **Interactive Charts**: Data visualization using Chart.js
- **Multi-dimensional Analysis**: 
  - Commit timeline analysis
  - File impact heatmap
  - Contributor statistics
  - Keyword frequency analysis
- **Internationalization**: English/Chinese interface switching

### 📈 Data Analysis

- **Commit Statistics**: Statistics by time, author, file type
- **Impact Analysis**: Analyzes the scope of code changes
- **Trend Analysis**: Time trends of RISC-V related development activities
- **Export Functionality**: Detailed scan reports in JSON format

## 📁 Project Structure

```
rvcommit-scanner/
├── git_commit_scanner/          # General Git commit scanner
│   ├── __init__.py
│   ├── cli.py                   # Command line interface
│   └── scanner.py               # Core scanning logic
├── rvcommit_scanner/            # RISC-V specialized scanner
│   ├── __init__.py
│   ├── cli.py                   # Main command line interface
│   ├── rv_keyword_scanner.py    # RISC-V keyword scanner
│   └── html/                    # Web interface resources
│       ├── index.html           # Main page
│       ├── styles.css           # Style files
│       └── js/                  # JavaScript files
├── test/                        # Test files and data
├── requirements.txt             # Python dependencies
├── setup.py                    # Installation configuration
└── README.md                   # Project documentation
```

## 🔧 Configuration Options

### Command Line Options Reference

#### rvcommit-scanner scan Command Options

| Option | Short | Type | Default | Description |
|--------|-------|------|---------|-------------|
| `--limit` | `-n` | Integer | Unlimited | Limit number of commits to scan |
| `--only-matched` | `-m` | Flag | False | Only show commits matching RISC-V keywords |
| `--only-once` | `--once` | Flag | False | Stop scanning after first match |
| `--output` | `-o` | Path | None | Specify JSON output file |
| `--web` | `-w` | Flag | False | Start web server after scanning |
| `--port` | `-p` | Integer | 8080 | Web server port number |
| `--fast-mode` | `-f` | Flag | False | Enable fast scan mode, skipping certain checks |

#### rvcommit-scanner web Command Options

| Option | Short | Type | Default | Description |
|--------|-------|------|---------|-------------|
| `--port` | `-p` | Integer | 8080 | Web server port number |
| `--data` | `-i` | Path | None | JSON data file to display |

#### git-scan Command Options

| Option | Short | Type | Default | Description |
|--------|-------|------|---------|-------------|
| `--regex` | `-r` | Flag | False | Enable regular expression matching |
| `--exclude` | `-e` | String | None | Exclude specified files or directories (regular expression) |
| `--type` | `-t` | String | all | Limit scan object types (all, commit, file, msg) |
| `--limit` | `-n` | Integer | Unlimited | Limit number of commits to scan |
| `--only-matched` | `-m` | Flag | False | Only show commits matching keywords |

### Scan Configuration

You can customize scanning rules by modifying keyword patterns in `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),
]
```

### Excluded Files

The following types of files are excluded by default:
- Package manager lock files (`package-lock.json`, `Cargo.lock`, etc.)
- Hidden files (files starting with `.`)
- Documentation files (like `.md`, etc.)
- Binary files

## 🚀 Performance Optimization

### Best Practices for Scanning Large Repositories

1. **Use limit options**: For large repositories, use `--limit` to restrict scan count
2. **Remote repository optimization**: Tool automatically optimizes clone depth based on `--limit` value
3. **Use `--only-matched`**: Only show matching commits to reduce output
4. **Use `--once`**: If you only need to find the first match, can stop quickly

```bash
# Optimization example: quickly scan recent 1000 commits of large repository
rvcommit-scanner scan https://github.com/torvalds/linux.git --limit 1000 --only-matched
```

## 🐛 Troubleshooting

### Common Issues and Solutions

**1. Remote Repository Clone Failed**
```bash
Error cloning repository: ...
```
Solutions:
- Check if URL is correct
- For SSH URLs, ensure SSH keys are configured
- Check network connectivity
- Try using HTTPS URL instead of SSH

**2. "Path does not exist" Error**
```bash
Error: Path '/path/to/repo' does not exist.
```
Solutions:
- Ensure path is correct
- Ensure directory is a Git repository
- Use absolute path

**3. Web Server Port Already in Use**
```bash
OSError: [Errno 48] Address already in use
```
Solutions:
- Use different port: `--port 9000`
- Stop program using the port
- Check port usage: `lsof -i :8080`

**4. Empty Scan Results**
Possible causes:
- Repository contains no RISC-V related commits
- Keyword matching rules are too strict
- Used `--limit` but matches are in earlier commits

Solutions:
- Increase `--limit` value
- Remove `--only-matched` option to see all scanned commits
- Check if repository contains relevant content

**5. Cannot Create JSON Output File**
Solutions:
- Check write permissions for output path
- Ensure output directory exists
- Use absolute path

## 📜 License

This project is licensed under the GPL-3.0 License - see the [LICENSE](LICENSE) file for details.

## 🤝 Contributors

- **jxzhu** - Initial work
- **Hein** - Core development and maintenance

## 🔗 Related Links

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