7000pctAUTO/gitpulse
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial upload: GitPulse - Developer Productivity Analyzer CLI tool
Some checks failed
CI / test (push) Has been cancelled
Details
CI / release (push) Has been cancelled
Details

Browse Source
This commit is contained in:
7000pctAUTO
2026-02-04 15:45:15 +00:00
parent 2dc0ee5b3f
commit a934e06783
1 changed files with 90 additions and 196 deletions
Download Patch File Download Diff File Expand all files Collapse all files

286
README.md
View File

@@ -1,252 +1,146 @@
# GitPulse - Local Git Analytics CLI
# GitPulse - Developer Productivity Analyzer
[![CI](https://7000pct.gitea.bloupla.net/7000pctAUTO/gitpulse/actions/workflows/ci.yml/badge.svg)](https://7000pct.gitea.bloupla.net/7000pctAUTO/gitpulse/actions)
[![Version](https://img.shields.io/pypi/v/gitpulse.svg)](https://pypi.org/project/gitpulse/)
[![Python](https://img.shields.io/pypi/pyversions/gitpulse.svg)](https://pypi.org/project/gitpulse/)
[![License](https://img.shields.io/pypi/l/gitpulse.svg)](https://opensource.org/licenses/MIT/)
A privacy-focused CLI tool that analyzes local Git repositories to visualize commit patterns, code churn, and developer productivity metrics using beautiful terminal visualizations with Rich. Runs entirely offline with no external data transmission.
GitPulse is a CLI tool that analyzes local git repositories to generate developer productivity reports. It provides commit frequency analysis, code churn tracking, contributor statistics, refactoring detection, and a beautiful terminal dashboard. Perfect for freelancers, consultants, and teams who want to understand their development patterns without external services.
## Features
- **Local Repository Analysis** - Analyze any local git repository without data transmission
- **Commit Activity Heatmap** - Display daily/weekly commit patterns as a GitHub-style heatmap
- **Code Churn Tracking** - Track lines added/deleted over time with trend visualization
- **Author Contribution Breakdown** - Show commit count, code changes, and contributions per author
- **Productivity Scorecard** - Calculate productivity scores based on commits, changes, and patterns
- **File Change Frequency** - Show most frequently changed files in the repository
- **Export Reports** - Export analysis results to Markdown and JSON formats
- **Time Range Filtering** - Filter analysis by custom time ranges (last week, month, custom dates)
## Why GitPulse?
In an era of increasing data privacy concerns, GitPulse stands out by:
- **100% Offline** - All data is processed locally and never transmitted
- **No External Dependencies** - No API calls, no cloud services, no tracking
- **Privacy First** - Your repository data stays on your machine
- **Beautiful Terminal UI** - Built with Rich for stunning visualizations
- **Commit Frequency Analysis**: Track commit patterns over time with daily, weekly, and monthly statistics
- **Code Churn Tracking**: Monitor lines added/removed and identify high-churn files
- **Contributor Statistics**: Calculate per-developer metrics including commits, changes, and activity patterns
- **Refactoring Detection**: Identify file renames and potential refactoring activity
- **JSON/CSV Export**: Export analysis results for external processing and reporting
- **Interactive Dashboard**: Visual terminal UI with charts and metrics (coming soon)
- **Time Period Filtering**: Analyze commits for specific time ranges using flexible date filters
- **Configuration**: Customizable settings via configuration file
## Installation
### From PyPI
```bash
pip install gitpulse
```
### From Source
```bash
git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/gitpulse.git
git clone https://github.com/gitpulse/gitpulse.git
cd gitpulse
pip install -e .
cargo build --release
cargo install --path .
```
### With Poetry
### From Cargo
```bash
poetry add gitpulse
cargo install gitpulse
```
## Quick Start
### Analyze a Repository
```bash
gitpulse analyze --path /path/to/repo
# Analyze the current repository (last 30 days)
gitpulse analyze
# Analyze with specific time period
gitpulse analyze --since 7d
gitpulse analyze --since 2024-01-01 --until 2024-01-31
# Export to JSON
gitpulse analyze --json > report.json
# Export to CSV
gitpulse export --format csv --output contributors.csv
```
### Show Commit Activity Heatmap
## Usage
### Analyze Command
The `analyze` command generates a comprehensive analysis report:
```bash
gitpulse heatmap --path /path/to/repo
gitpulse analyze [OPTIONS]
Options:
-s, --since <PERIOD> Time period (e.g., 7d, 2w, 1m, 1y)
-u, until <DATE> End date for analysis
-c, --commits <N> Analyze last N commits
--include-merges Include merge commits
--no-churn Skip code churn analysis
--no-refactor Skip refactoring detection
--json Output in JSON format
--history Show commit history
--top <N> Limit to top N contributors
-o, --output <PATH> Output file path (for JSON/CSV)
```
### View Code Churn Trends
### Export Command
Export analysis results in various formats:
```bash
gitpulse churn --path /path/to/repo --since "2024-01-01"
gitpulse export --format json --output report.json
gitpulse export --format csv --output contributors.csv
```
### See Author Contributions
### Dashboard Command
Launch the interactive terminal dashboard (coming soon):
```bash
gitpulse authors --path /path/to/repo
gitpulse dashboard
```
### Check Productivity Scores
```bash
gitpulse productivity --path /path/to/repo
```
### Export a Report
```bash
gitpulse export --path /path/to/repo --format markdown --output report.md
gitpulse export --path /path/to/repo --format json --output report.json
```
## Commands
| Command | Description |
|---------|-------------|
| `gitpulse analyze` | Show an overview dashboard with all metrics |
| `gitpulse heatmap` | Display commit activity as a calendar-style heatmap |
| `gitpulse churn` | Show code churn trends (lines added/deleted) |
| `gitpulse authors` | Display author contribution breakdown |
| `gitpulse productivity` | Show productivity scorecards |
| `gitpulse export` | Export analysis results to Markdown or JSON |
## Options
### Global Options
| Option | Description |
|--------|-------------|
| `--path PATH` | Path to git repository (default: current directory) |
| `--since DATE` | Start date for analysis (e.g., "2024-01-01" or "1 week ago") |
| `--until DATE` | End date for analysis |
| `--verbose` | Enable verbose output |
| `--help` | Show help message |
| `--version` | Show version |
### Date Formats
GitPulse supports various date formats:
- ISO format: `2024-01-01`
- Relative time: `1 week ago`, `2 months ago`, `3 days ago`
- Full datetime: `2024-01-01T12:00:00`
## Configuration
### Environment Variables
```bash
export GITPULSE_DEFAULT_PATH=/path/to/your/repo
export GITPULSE_CACHE_ENABLED=true
```
### Configuration File
Create `~/.config/gitpulse/config.toml`:
GitPulse uses a configuration file located at `~/.config/gitpulse/config.toml`:
```toml
[default]
path = "/path/to/default/repo"
cache_enabled = true
[analysis]
default_time_period = "30 days"
max_contributors = 50
include_merges = false
refactoring_detection = true
[display]
theme = "default"
compact = false
theme = "dark"
chart_height = 10
compact_tables = false
show_sparklines = true
[export]
default_format = "json"
include_timestamps = true
indent_json = true
```
## Architecture
## Environment Variables
```
gitpulse/
├── cli.py # Main CLI entry point with Click commands
├── config.py # Configuration management
├── __init__.py # Package metadata
├── analyzers/ # Analysis engines
│ ├── base.py # Base analyzer class
│ ├── commit_analyzer.py # Commit pattern analysis
│ ├── churn_analyzer.py # Code churn tracking
│ ├── author_analyzer.py # Author contribution analysis
│ └── productivity_analyzer.py # Productivity scoring
├── ui/ # Terminal visualizations
│ ├── heatmap.py # Calendar-style heatmaps
│ ├── charts.py # Bar and line charts
│ ├── tables.py # Styled tables
│ └── render.py # Combined rendering
├── exporters/ # Export functionality
│ ├── markdown_exporter.py
│ └── json_exporter.py
└── utils/ # Utility functions
├── git_utils.py # Git repository access
└── date_utils.py # Date parsing
```
- `GITPULSE_CONFIG`: Path to custom config file
- `GITPULSE_THEME`: Override dashboard theme (dark/light)
- `GITPULSE_NO_COLOR`: Disable colored output
## Development
### Setup Development Environment
## Building from Source
```bash
git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/gitpulse.git
cd gitpulse
poetry install --with dev
# Development build
cargo build
# Release build with optimizations
cargo build --release
# Run tests
cargo test
# Run with logging
RUST_LOG=debug cargo run -- analyze
```
### Run Tests
```bash
pytest tests/ -v
pytest tests/ --cov=gitpulse
```
### Linting
```bash
ruff check .
```
### Type Checking
```bash
mypy gitpulse/
```
## Dependencies
### Core Dependencies
- `rich>=13.0.0` - Terminal rendering and visualizations
- `gitpython>=3.1.0` - Git repository access
- `pandas>=2.0.0` - Data manipulation and analysis
- `click>=8.0.0` - CLI framework
### Development Dependencies
- `pytest>=7.0.0` - Testing framework
- `pytest-cov>=4.0.0` - Coverage reporting
## Privacy
GitPulse is designed with privacy as its core principle:
- **No Network Requests** - Zero external API calls
- **Local Processing** - All git data is processed locally
- **No Data Storage** - No caching of repository data
- **No Telemetry** - No usage tracking or analytics
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
GitPulse is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Acknowledgments
- [Rich](https://github.com/Textualize/rich) for the amazing terminal rendering library
- [GitPython](https://github.com/gitpython-developers/GitPython) for git repository access
- Inspired by [Prism.Tools](https://prism.tools/) and similar privacy-focused developer tools
## Changelog
### v0.1.0 (2024-01-31)
- Initial release
- Core CLI with analyze, heatmap, churn, authors, productivity commands
- Export functionality (Markdown and JSON)
- Time range filtering
- Privacy-focused offline processing
- Built with [clap](https://github.com/clap-rs/clap) for CLI
- Uses [git2](https://github.com/rust-lang/git2-rs) for git operations
- Terminal UI powered by [ratatui](https://github.com/ratatui/ratatui)