gitsense 0.1.1

CLI tool for analyzing git repositories

🔍 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.

---

✨ 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

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

# Install in development mode
pip install -e .

Basic Usage

# Analyze the current repository
gitsense analyze

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

---

📖 Usage Examples

Default Analysis (Current Directory)

$ 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

$ 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

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

Verify Installation

gitsense --help

Run Tests (if available)

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:

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

Command Not Found

If gitsense command isn't recognized:

# 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

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 file for details.

---

👥 Author

Build and Break - Crafting tools for better development

---

📞 Support & Feedback

• 🐛 Found a bug? Open an issue
• 💭 Have an idea? Suggest a feature
• 📧 Questions? Feel free to reach out

---

🙏 Acknowledgments

Built with:

• Typer - For elegant CLI creation
• Rich - For beautiful terminal output
• GitPython - For git repository interaction

---

Made with ❤️ for developers who care about code quality