165 lines
3.3 KiB
Markdown
165 lines
3.3 KiB
Markdown
# Git Diff Explainer CLI
|
|
|
|
A CLI tool that parses git diffs and provides intelligent, contextual explanations of code changes. Identifies programming language, summarizes changes, flags potential issues, and suggests improvements - all running locally without external API dependencies.
|
|
|
|
## Features
|
|
|
|
- **Parse git diffs/patches**: Extract file names, hunks, and code changes from unified diff format
|
|
- **Identify programming language**: Detect language from file extensions and code patterns
|
|
- **Summarize changes**: Generate human-readable summaries of what each change does
|
|
- **Flag potential issues**: Detect bugs, security vulnerabilities, and code smells
|
|
- **Suggest improvements**: Provide specific refactoring suggestions
|
|
- **Local execution**: Runs entirely offline using local libraries
|
|
- **Color-coded output**: Terminal output with ANSI colors for better readability
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
# Using pip
|
|
pip install git-diff-explainer-cli
|
|
|
|
# From source
|
|
git clone <repository>
|
|
cd git-diff-explainer-cli
|
|
pip install -e .
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Basic Usage
|
|
|
|
```bash
|
|
# Explain a diff from stdin
|
|
git diff | gdiffer explain --stdin
|
|
|
|
# Explain a diff file
|
|
gdiffer explain --file changes.diff
|
|
|
|
# Pass diff as argument
|
|
gdiffer explain "diff --git a/file.py b/file.py..."
|
|
|
|
# Get just the summary
|
|
gdiffer summarize --file changes.diff
|
|
|
|
# Check for issues only
|
|
gdiffer issues --file changes.diff
|
|
```
|
|
|
|
### Options
|
|
|
|
```bash
|
|
# Output format: terminal (default), json, plain
|
|
gdiffer explain --output json
|
|
|
|
# Verbose output
|
|
gdiffer explain --verbose
|
|
```
|
|
|
|
## Examples
|
|
|
|
### Simple Diff Explanation
|
|
|
|
```bash
|
|
$ git diff | gdiffer explain
|
|
=== Git Diff Analysis Summary ===
|
|
Total files changed: 1
|
|
Files added: 0
|
|
Files deleted: 0
|
|
Files modified: 1
|
|
Total changes: 3
|
|
|
|
Languages:
|
|
- python: 1 files
|
|
|
|
=== File Changes ===
|
|
|
|
1. src/main.py
|
|
Status: modify
|
|
Changes: 3 lines
|
|
Hunk 1:
|
|
+import os
|
|
+import sys
|
|
def main():
|
|
print("Hello, World!")
|
|
```
|
|
|
|
### JSON Output
|
|
|
|
```bash
|
|
$ gdiffer explain --output json "diff --git a/test.py..."
|
|
{
|
|
"summary": {
|
|
"total_files": 1,
|
|
"files_added": 0,
|
|
"files_deleted": 0,
|
|
"files_modified": 1,
|
|
"total_changes": 2
|
|
},
|
|
"files": [...]
|
|
}
|
|
```
|
|
|
|
### Issue Detection
|
|
|
|
```bash
|
|
$ gdiffer issues --file sql_injection.diff
|
|
[CRITICAL] Potential SQL Injection
|
|
File: db.py:5
|
|
Description: String concatenation or interpolation used in SQL query
|
|
Suggestion: Use parameterized queries or ORM methods
|
|
```
|
|
|
|
## Supported Languages
|
|
|
|
- Python
|
|
- JavaScript / TypeScript
|
|
- Java
|
|
- Go
|
|
- Rust
|
|
- C / C++
|
|
- Ruby
|
|
- PHP
|
|
- And more...
|
|
|
|
## Configuration
|
|
|
|
Environment variables:
|
|
|
|
| Variable | Description | Default |
|
|
|----------|-------------|---------|
|
|
| `GDIFF_OUTPUT` | Output format: terminal, json, plain | terminal |
|
|
| `GDIFF_VERBOSE` | Enable verbose output | false |
|
|
|
|
## Development
|
|
|
|
```bash
|
|
# Install development dependencies
|
|
pip install -e ".[dev]"
|
|
|
|
# Run tests
|
|
pytest tests/ -v
|
|
|
|
# Run with coverage
|
|
pytest tests/ --cov=src/gdiffer
|
|
|
|
# Type checking
|
|
mypy src/gdiffer/
|
|
|
|
# Linting
|
|
ruff check src/gdiffer/
|
|
```
|
|
|
|
## Error Handling
|
|
|
|
Common errors and solutions:
|
|
|
|
| Error | Solution |
|
|
|-------|----------|
|
|
| Invalid git diff format | Provide a valid unified diff format |
|
|
| No changes detected | Ensure the diff contains actual code changes |
|
|
| Unsupported language | Use a supported language or file extension |
|
|
|
|
## License
|
|
|
|
MIT
|