This commit is contained in:
171
README.md
171
README.md
@@ -2,7 +2,7 @@
|
||||
|
||||
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)
|
||||
|
||||
|
||||
|
||||
@@ -98,15 +98,14 @@ Export analysis results to a file in the specified format.
|
||||
git-insights export [OPTIONS] [PATH]
|
||||
|
||||
Options:
|
||||
--days INTEGER Number of days to analyze (default: 30)
|
||||
--format TEXT Output format: json, markdown, html (default: json)
|
||||
--output FILE Output file path (default: stdout)
|
||||
--output TEXT Output file path
|
||||
```
|
||||
|
||||
**Example:**
|
||||
|
||||
```bash
|
||||
git-insights export /my/project --format markdown --output report.md
|
||||
git-insights export /my/project --format json --output report.json
|
||||
```
|
||||
|
||||
### report
|
||||
@@ -118,23 +117,25 @@ git-insights report [OPTIONS] [PATH]
|
||||
|
||||
Options:
|
||||
--days INTEGER Number of days to analyze (default: 30)
|
||||
--output FILE Output file path
|
||||
--output TEXT Output file path for HTML report
|
||||
```
|
||||
|
||||
**Example:**
|
||||
|
||||
```bash
|
||||
git-insights report /my/project --output report.html
|
||||
git-insights report /my/project --days 30 --output report.html
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
Create a `.git-insights/config.yaml` file in your project root or home directory:
|
||||
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: "."
|
||||
repository_path: .
|
||||
analysis_days: 30
|
||||
output_format: "json"
|
||||
output_format: json
|
||||
churn_threshold: 500
|
||||
risky_commit_threshold: 500
|
||||
merge_commit_flag: true
|
||||
@@ -142,58 +143,8 @@ merge_commit_flag: true
|
||||
|
||||
### Environment Variables
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| GIT_INSIGHTS_REPO_PATH | "." | Repository path to analyze |
|
||||
| GIT_INSIGHTS_DAYS | "30" | Default analysis period in days |
|
||||
| GIT_INSIGHTS_OUTPUT_FORMAT | "json" | Default output format |
|
||||
|
||||
## Output Formats
|
||||
|
||||
### Console Dashboard
|
||||
|
||||
The default console output uses Rich library to display colorful, formatted metrics directly in your terminal:
|
||||
|
||||
```
|
||||
╔════════════════════════════════════════════════════════════╗
|
||||
║ Git Insights - Productivity Dashboard ║
|
||||
╠════════════════════════════════════════════════════════════╣
|
||||
║ Total Commits: 147 │ Authors: 5 ║
|
||||
║ Lines Added: 12,453 │ Lines Deleted: 4,231 ║
|
||||
╚════════════════════════════════════════════════════════════╝
|
||||
```
|
||||
|
||||
### JSON
|
||||
|
||||
```json
|
||||
{
|
||||
"summary": {
|
||||
"total_commits": 147,
|
||||
"authors": 5,
|
||||
"lines_added": 12453,
|
||||
"lines_deleted": 4231
|
||||
},
|
||||
"commit_patterns": {...},
|
||||
"code_churn": {...}
|
||||
}
|
||||
```
|
||||
|
||||
### Markdown
|
||||
|
||||
```markdown
|
||||
# Git Insights Report
|
||||
|
||||
## Summary
|
||||
|
||||
| Metric | Value |
|
||||
|--------|-------|
|
||||
| Total Commits | 147 |
|
||||
| Authors | 5 |
|
||||
```
|
||||
|
||||
### HTML
|
||||
|
||||
Generates a self-contained HTML report with interactive charts and tables.
|
||||
- `GIT_INSIGHTS_REPO_PATH` - Override repository path
|
||||
- `GIT_INSIGHTS_DAYS` - Default number of days to analyze
|
||||
|
||||
## Development
|
||||
|
||||
@@ -212,10 +163,23 @@ source venv/bin/activate # On Windows: venv\Scripts\activate
|
||||
pip install -e ".[dev]"
|
||||
|
||||
# Run tests
|
||||
pytest tests/ -v --cov=src
|
||||
pytest tests/ -v
|
||||
|
||||
# Run linting
|
||||
python -m ruff check src/ tests/
|
||||
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
|
||||
@@ -223,61 +187,33 @@ python -m ruff check src/ tests/
|
||||
```
|
||||
git-insights-cli/
|
||||
├── src/
|
||||
│ ├── __init__.py # Package marker with version
|
||||
│ ├── cli.py # CLI commands and entry point
|
||||
│ ├── git_insights.py # Main orchestrator class
|
||||
│ ├── git_insights.py # Main orchestrator
|
||||
│ ├── cli.py # CLI commands
|
||||
│ ├── analyzers/
|
||||
│ │ ├── __init__.py
|
||||
│ │ ├── git_repository.py # Git repository wrapper
|
||||
│ │ ├── commit_pattern.py # Commit pattern analysis
|
||||
│ │ ├── code_churn.py # Code churn tracking
|
||||
│ │ ├── risky_commit.py # Risky commit detection
|
||||
│ │ └── velocity.py # Velocity analysis
|
||||
│ ├── formatters/
|
||||
│ │ ├── __init__.py
|
||||
│ │ ├── base.py # Base formatter abstract class
|
||||
│ │ ├── json_formatter.py # JSON output
|
||||
│ │ ├── markdown_formatter.py # Markdown output
|
||||
│ │ ├── html_formatter.py # HTML output
|
||||
│ │ └── dashboard.py # Rich console dashboard
|
||||
│ │ ├── 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/
|
||||
│ │ ├── __init__.py
|
||||
│ │ └── data_structures.py # Dataclass 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/
|
||||
│ ├── __init__.py
|
||||
│ ├── date_utils.py # Date/time utilities
|
||||
│ └── config.py # Configuration loader
|
||||
│ ├── date_utils.py # Date utilities
|
||||
│ └── config.py # Configuration loading
|
||||
├── tests/
|
||||
│ ├── __init__.py
|
||||
│ ├── conftest.py # Pytest fixtures
|
||||
│ ├── test_cli.py # CLI tests
|
||||
│ ├── test_models.py # Model tests
|
||||
│ ├── test_analyzers.py # Analyzer tests
|
||||
│ └── test_formatters.py # Formatter tests
|
||||
├── .git-insights/
|
||||
│ └── config.yaml # Default configuration
|
||||
├── .gitea/
|
||||
│ └── workflows/
|
||||
│ └── ci.yml # Gitea Actions CI workflow
|
||||
├── requirements.txt # Dependencies
|
||||
├── setup.py # Package setup
|
||||
├── pyproject.toml # Project configuration
|
||||
├── .gitignore # Git ignore patterns
|
||||
├── .pre-commit-config.yaml # Pre-commit hooks
|
||||
└── README.md # This file
|
||||
```
|
||||
|
||||
### Running Tests
|
||||
|
||||
```bash
|
||||
# Run all tests
|
||||
pytest tests/ -v
|
||||
|
||||
# Run with coverage
|
||||
pytest tests/ -v --cov=src --cov-report=term-missing
|
||||
|
||||
# Run specific test file
|
||||
pytest tests/test_cli.py -v
|
||||
│ ├── 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
|
||||
@@ -287,10 +223,3 @@ 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.
|
||||
|
||||
## Acknowledgments
|
||||
|
||||
- [Click](https://click.palletsprojects.com/) - CLI framework
|
||||
- [Rich](https://github.com/Textualize/rich) - Terminal formatting
|
||||
- [GitPython](https://gitpython.readthedocs.io/) - Git bindings
|
||||
- [Jinja2](https://jinja.palletsprojects.com/) - Template engine
|
||||
|
||||
Reference in New Issue
Block a user