226 lines
5.6 KiB
Markdown
226 lines
5.6 KiB
Markdown
# Git Insights CLI
|
|
|
|
A powerful CLI tool that analyzes git repositories to generate developer productivity insights, code quality metrics, and commit pattern analysis. Works entirely offline using local git data with no external API dependencies.
|
|
|
|
[](https://7000pct.gitea.bloupla.net/7000pctAUTO/git-insights-cli/actions)
|
|
|
|
|
|
|
|
## Features
|
|
|
|
- **Commit Pattern Analysis** - Analyze commit frequency, time patterns, and author contributions
|
|
- **Code Churn Tracking** - Track lines added/removed per commit and identify high churn areas
|
|
- **Productivity Metrics Dashboard** - Display metrics in a formatted terminal dashboard using Rich
|
|
- **Risky Commit Detection** - Identify commits with large changes, merge commits, and revert commits
|
|
- **Team Velocity Reports** - Calculate commit velocity and throughput over time periods
|
|
- **Export to Multiple Formats** - Export analysis results to JSON, HTML, and Markdown formats
|
|
|
|
## Installation
|
|
|
|
### From Source
|
|
|
|
```bash
|
|
pip install -e .
|
|
```
|
|
|
|
### Dependencies
|
|
|
|
- Python 3.8+
|
|
- Click 8.1.7+
|
|
- Rich 13.7.0+
|
|
- GitPython 3.1.40+
|
|
- dataclasses-json 0.6.4+
|
|
- PyYAML 6.0.1+
|
|
- Jinja2 3.1.3+
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# Analyze current repository (last 30 days)
|
|
git-insights analyze
|
|
|
|
# Analyze specific repository
|
|
git-insights analyze /path/to/repo
|
|
|
|
# Show productivity dashboard
|
|
git-insights dashboard
|
|
|
|
# Export to JSON
|
|
git-insights export --format json
|
|
|
|
# Analyze last 7 days
|
|
git-insights analyze --days 7
|
|
```
|
|
|
|
## Commands
|
|
|
|
### analyze
|
|
|
|
Analyze a git repository for commit patterns, code churn, and productivity metrics.
|
|
|
|
```bash
|
|
git-insights analyze [OPTIONS] [PATH]
|
|
|
|
Options:
|
|
--days INTEGER Number of days to analyze (default: 30)
|
|
--format TEXT Output format: json, markdown, html (default: console)
|
|
-v, --verbose Enable verbose output
|
|
```
|
|
|
|
**Example:**
|
|
|
|
```bash
|
|
git-insights analyze /my/project --days 7 --format json
|
|
```
|
|
|
|
### dashboard
|
|
|
|
Display productivity metrics in an interactive terminal dashboard.
|
|
|
|
```bash
|
|
git-insights dashboard [OPTIONS] [PATH]
|
|
|
|
Options:
|
|
--days INTEGER Number of days to analyze (default: 30)
|
|
```
|
|
|
|
**Example:**
|
|
|
|
```bash
|
|
git-insights dashboard /my/project
|
|
```
|
|
|
|
### export
|
|
|
|
Export analysis results to a file in the specified format.
|
|
|
|
```bash
|
|
git-insights export [OPTIONS] [PATH]
|
|
|
|
Options:
|
|
--format TEXT Output format: json, markdown, html (default: json)
|
|
--output TEXT Output file path
|
|
```
|
|
|
|
**Example:**
|
|
|
|
```bash
|
|
git-insights export /my/project --format json --output report.json
|
|
```
|
|
|
|
### report
|
|
|
|
Generate a comprehensive productivity report.
|
|
|
|
```bash
|
|
git-insights report [OPTIONS] [PATH]
|
|
|
|
Options:
|
|
--days INTEGER Number of days to analyze (default: 30)
|
|
--output TEXT Output file path for HTML report
|
|
```
|
|
|
|
**Example:**
|
|
|
|
```bash
|
|
git-insights report /my/project --days 30 --output report.html
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Git Insights CLI supports configuration via YAML files. Create a `.git-insights/config.yaml` file in your repository or use `~/.git-insights/config.yaml` for user-wide settings.
|
|
|
|
### Default Configuration
|
|
|
|
```yaml
|
|
repository_path: .
|
|
analysis_days: 30
|
|
output_format: json
|
|
churn_threshold: 500
|
|
risky_commit_threshold: 500
|
|
merge_commit_flag: true
|
|
```
|
|
|
|
### Environment Variables
|
|
|
|
- `GIT_INSIGHTS_REPO_PATH` - Override repository path
|
|
- `GIT_INSIGHTS_DAYS` - Default number of days to analyze
|
|
|
|
## Development
|
|
|
|
### Setup
|
|
|
|
```bash
|
|
# Clone the repository
|
|
git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/git-insights-cli.git
|
|
cd git-insights-cli
|
|
|
|
# Create virtual environment
|
|
python -m venv venv
|
|
source venv/bin/activate # On Windows: venv\Scripts\activate
|
|
|
|
# Install dependencies
|
|
pip install -e ".[dev]"
|
|
|
|
# Run tests
|
|
pytest tests/ -v
|
|
|
|
# Run linting
|
|
ruff check .
|
|
```
|
|
|
|
### Running Tests
|
|
|
|
```bash
|
|
# Run all tests with coverage
|
|
pytest tests/ -v --cov=src --cov-report=term-missing
|
|
|
|
# Run specific test file
|
|
pytest tests/test_cli.py -v
|
|
|
|
# Run with verbose output
|
|
pytest tests/ -vv
|
|
```
|
|
|
|
### Project Structure
|
|
|
|
```
|
|
git-insights-cli/
|
|
├── src/
|
|
│ ├── git_insights.py # Main orchestrator
|
|
│ ├── cli.py # CLI commands
|
|
│ ├── analyzers/
|
|
│ │ ├── git_repository.py # Git repository wrapper
|
|
│ │ ├── commit_pattern.py # Commit pattern analysis
|
|
│ │ ├── code_churn.py # Code churn tracking
|
|
│ │ ├── velocity.py # Velocity analysis
|
|
│ │ └── risky_commit.py # Risky commit detection
|
|
│ ├── models/
|
|
│ │ └── data_structures.py # Data models
|
|
│ ├── formatters/
|
|
│ │ ├── base.py # Base formatter
|
|
│ │ ├── json_formatter.py # JSON output
|
|
│ │ ├── markdown_formatter.py # Markdown output
|
|
│ │ ├── html_formatter.py # HTML output
|
|
│ │ └── dashboard.py # Terminal dashboard
|
|
│ └── utils/
|
|
│ ├── date_utils.py # Date utilities
|
|
│ └── config.py # Configuration loading
|
|
├── tests/
|
|
│ ├── conftest.py # Pytest fixtures
|
|
│ ├── test_cli.py # CLI tests
|
|
│ ├── test_models.py # Model tests
|
|
│ └── test_formatters.py # Formatter tests
|
|
├── pyproject.toml # Project configuration
|
|
├── requirements.txt # Dependencies
|
|
└── README.md # This file
|
|
```
|
|
|
|
## Contributing
|
|
|
|
Contributions are welcome! Please feel free to submit a Pull Request.
|
|
|
|
## License
|
|
|
|
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|