Metadata-Version: 2.4
Name: gitsense
Version: 0.1.1
Summary: CLI tool for analyzing git repositories
Author: Build and Break
License-File: LICENSE
Requires-Dist: gitpython
Requires-Dist: rich
Requires-Dist: typer
Description-Content-Type: text/markdown

# 🔍 GitSense

> **Intelligent Git Repository Analysis at Your Fingertips**

A powerful CLI tool that analyzes git repositories to provide actionable insights about code health, team contributions, and commit quality. GitSense helps you understand repository patterns, identify risk hotspots, and maintain high code standards.

![Version](https://img.shields.io/badge/version-0.1.0-blue)
![Python](https://img.shields.io/badge/python-3.8+-green)
![License](https://img.shields.io/badge/license-MIT-blueviolet)

---

## ✨ Features

### 🧑‍💼 Contributor Analytics

- **Top Contributors**: Identify your most active team members
- Ranked by commit count over the repository history
- Quick insight into team engagement patterns

### 🔥 Risk Hotspot Detection

- **File Churn Analysis**: Spot files that change frequently
- Identify potential stability concerns in your codebase
- Focus refactoring efforts on high-volatility areas

### 🧠 Commit Quality Scoring

- **Intelligent Quality Assessment**: Evaluate commit hygiene
- Detects common bad patterns (vague messages, incomplete descriptions)
- Scores from 0-100 based on commit message standards
- Encourages better documentation practices

### 📊 Rich Terminal Output

- Beautiful formatted tables and panels
- Color-coded results for easy scanning
- Intuitive visual hierarchy

---

## 🚀 Quick Start

### Installation

```bash
# Clone the repository
git clone https://github.com/buildandbreak-bnb/gitsense.git
cd gitsense

# Install in development mode
pip install -e .
```

### Basic Usage

```bash
# Analyze the current repository
gitsense analyze

# Analyze a specific repository
gitsense analyze /path/to/repo
```

---

## 📖 Usage Examples

### Default Analysis (Current Directory)

```bash
$ gitsense analyze
```

This will display:

- **Top 5 Contributors**: Shows who has been most active
- **Most Changed Files**: Highlights files with high churn
- **Commit Quality Score**: Overall assessment of commit messages

### Analyze a Specific Repository

```bash
$ gitsense analyze ~/projects/my-awesome-project
$ gitsense
```

### Example Output

```
╭─────────────────────────────────────────╮
│         🚀 GitSense Analysis            │
╰─────────────────────────────────────────╯

     Top Contributors
┏━━━━━━━━━━━━━┳━━━━━━━━━┓
┃ Name        ┃ Commits ┃
┡━━━━━━━━━━━━━╇━━━━━━━━━┩
│ Alice Chen  │ 342     │
│ Bob Smith   │ 289     │
│ Carol White │ 156     │
└─────────────┴─────────┘

🔥 Most Changed Files (Risk Hotspots)
┏━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┓
┃ File              ┃ Changes ┃
┡━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━┩
│ src/main.py       │ 156     │
│ tests/test_api.py │ 98      │
│ config/settings.py│ 67      │
└───────────────────┴─────────┘

╭──────────────────────────────────────────╮
│   🧠 Commit Quality Score: 78/100        │
╰──────────────────────────────────────────╯
```

---

## 📊 Metrics Explained

### Top Contributors

Displays the 5 most active developers by commit count (last 1000 commits). Useful for:

- Understanding team activity distribution
- Identifying code owners
- Recognizing consistent contributors

### File Churn (Risk Hotspots)

Shows the 5 most frequently modified files (last 500 commits). Files with high churn may indicate:

- Areas under active development
- Unstable or complex code
- Code that needs refactoring
- Potential quality issues

**Use this to:** Focus code reviews, refactoring efforts, and testing on high-churn files.

### Commit Quality Score

Analyzes the last 200 commits and assigns a score (0-100) based on:

- **Message Length**: Encourages descriptive commit messages (minimum 5 characters)
- **Message Clarity**: Flags vague messages like "fix", "update", "stuff", "asdf", "wip"
- **Overall Hygiene**: Rewards thoughtful, well-documented commits

**Scoring Rules:**

- `-1` point: Message shorter than 5 characters
- `-1` point: Weak commit message containing "fix" but too short
- `-2` points: Anti-pattern messages (update, stuff, asdf, wip)

**Interpretation:**

- **80-100**: Excellent commit practice
- **60-79**: Good, with room for improvement
- **40-59**: Needs attention to commit message quality
- **0-39**: Significant quality concerns

---

## 🛠️ Architecture

```
gitsense/
├── __init__.py          # Package initialization
├── main.py              # CLI entry point (Typer commands)
├── analyzer.py          # Git repository interface
└── metrics/
    ├── __init__.py
    ├── contributors.py  # Top contributors metric
    ├── churn.py         # File churn analysis
    └── scoring.py       # Commit quality scoring
```

### Key Components

**main.py**: CLI interface using Typer

- Orchestrates analysis workflow
- Formats and displays results with Rich

**analyzer.py**: Repository wrapper

- Loads git repositories safely
- Provides error handling for invalid paths

**metrics/**: Analysis engines

- `contributors.py`: Author frequency analysis
- `churn.py`: File modification tracking
- `scoring.py`: Commit message evaluation

---

## 📋 Requirements

- **Python**: 3.8 or higher
- **Dependencies**:
  - `typer` - Modern Python CLI framework
  - `rich` - Beautiful terminal formatting
  - `gitpython` - Python Git library

See `pyproject.toml` for exact version specifications.

---

## 🔧 Installation & Development

### Clone & Install

```bash
git clone https://github.com/buildandbreak-bnb/gitsense.git
cd gitsense
pip install -e .
```

### Verify Installation

```bash
gitsense --help
```

### Run Tests (if available)

```bash
pytest
```

---

## 💡 Use Cases

### 📈 Team Onboarding

Run GitSense to show new team members who the domain experts are and where code changes happen most frequently.

### 🎯 Code Review Focus

Prioritize deeper reviews for high-churn files identified by file churn analysis.

### 📝 Quality Improvement

Check commit quality scores regularly to maintain standards and encourage better documentation.

### 🔍 Codebase Health Audit

Use GitSense as part of regular repository health assessments.

### 🚨 Identify Risk Areas

Quick identification of unstable areas of the codebase that may need refactoring.

---

## 🐛 Troubleshooting

### Error: "Not a git repository"

```
❌ Not a git repository.
👉 Run inside a repo or pass a path:
   gitsense analyze /path/to/repo
```

**Solution**: Run gitsense inside a git repository or provide the full path:

```bash
gitsense analyze /path/to/your/git/repo
```

### Command Not Found

If `gitsense` command isn't recognized:

```bash
# Reinstall in development mode
pip install -e .
```

---

## 🚦 Roadmap

- [ ] Additional metrics (code complexity, test coverage)
- [ ] Export results to JSON/CSV
- [ ] Custom time range filtering
- [ ] Integration with CI/CD pipelines
- [ ] Repository comparison tools
- [ ] Configuration file support
- [ ] Advanced filtering and sorting

---

## 🤝 Contributing

Contributions are welcome! Please follow these guidelines:

1. **Fork** the repository
2. **Create** a 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

### Development Setup

```bash
git clone https://github.com/buildandbreak-bnb/gitsense.git
cd gitsense
pip install -e ".[dev]"
```

---

## 📄 License

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

---

## 👥 Author

**Build and Break** - _Crafting tools for better development_

---

## 📞 Support & Feedback

- 🐛 **Found a bug?** [Open an issue](https://github.com/buildandbreak-bnb/gitsense/issues)
- 💭 **Have an idea?** [Suggest a feature](https://github.com/buildandbreak-bnb/gitsense/issues)
- 📧 **Questions?** Feel free to reach out

---

## 🙏 Acknowledgments

Built with:

- [Typer](https://typer.tiangolo.com/) - For elegant CLI creation
- [Rich](https://rich.readthedocs.io/) - For beautiful terminal output
- [GitPython](https://gitpython.readthedocs.io/) - For git repository interaction

---

**Made with ❤️ for developers who care about code quality**
