CLI tool that scores git commit messages against best practices (imperative mood, length, scope tags, co-author attribution). Reads git repo history, generates quality report with per-author trends.

Quick Start • Features • Examples • Contributing

What is this?

CommitLens is a standalone command‑line interface that reads a local Git repository, scores each commit message against hygiene rules, and reports quality trends per author. It is designed for solo AI developers and small teams who want fast, offline feedback on commit message consistency.

Example usage:

$ commitlens analyze --since 2024-01-01 --format text
Author     Commits  Avg Score  Trend
alice          14       82       -3
bob             6       90

Problem

AI-assisted development produces high commit volume with inconsistent message quality. Teams and solo developers have no automated way to audit commit hygiene or track improvement over time.

Features

Feature	Description
Commit Message Scoring	Evaluates each commit on imperative mood, subject length ≤72, presence of a scope tag, and correct co‑author trailer format.
Per‑Author Trend Analysis	Calculates average score and trend (average of last 5 commits vs. previous 5) for each author with sufficient history.
CLI Report Generation	Outputs a human‑readable table or machine‑readable JSON via commitlens analyze.
Offline Git Log Processing	Uses only local git log; no external services or network calls required.
Configurable Analysis Window	Accept --repo and --since flags (or environment variables) to define the commit range.
Extendable Scoring Rules	Modify or add rules in scorer.py without touching core logic.
Tested Suite	Unit tests for scorer, aggregator, and CLI ensure reliability.

Quick Start

1. Clone the repository:

   git clone https://github.com/yourusername/CommitLens.git
   

2. Enter the project directory:

   cd CommitLens
   

3. Install the package in development mode:

   pip install -e .
   

4. Run your first analysis (text format, last month):

   commitlens analyze --since 1.month.ago --format text
   

Examples

Basic text report
Show a quick summary of commit quality for the default branch.

$ commitlens analyze --format text
Author     Commits  Avg Score  Trend
alice          18       76       -4
charlie         9       88

JSON output for CI integration
Emit machine‑readable data for automated workflows.

$ commitlens analyze --since 2024-06-01 --format json
{
  "repo": ".",
  "analyzed_range": {
    "since": "2024-06-01",
    "until": "HEAD"
  },
  "total_commits": 27,
  "authors": {
    "alice": {
      "commit_count": 12,
      "average_score": 78,
      "trend": -6
    },
    "bob": {
      "commit_count": 8,
      "average_score": 92
    }
  }
}

Custom branch and date range
Analyse a feature branch from the start of the year.

$ commitlens analyze --repo . --since 2024-01-01 --format text
Author     Commits  Avg Score  Trend
alice          22       81       0
dave            5       70

File Structure

CommitLens/
  commitlens/          # Core source code
    __init__.py
    cli.py             # Click command group and `analyze` subcommand
    scorer.py          # Commit scoring logic (Feature 1)
    aggregator.py      # Per‑author statistics and trend (Feature 2)
    reporter.py        # Text/JSON rendering (Feature 3)
    models.py          # Commit & ScoredCommit dataclasses
    utils.py           # Helpers: git log parsing, date parsing
  tests/               # Test suite
    __init__.py
    test_scorer.py
    test_aggregator.py
    test_cli.py
  assets/              # Documentation graphics
    infographic.png
  pyproject.toml
  README.md
  LICENSE

Tech Stack

Technology	Purpose
Python 3.11+	Core language runtime
Click	Declarative CLI framework
Git	Local repository history extraction
Python standard library (re, datetime, collections)	Scoring logic implementation
pytest	Unit testing framework

Contributing

Fork the repository.
Make your changes in a feature branch.
Run the test suite with pytest.
Submit a pull request for review.

License

MIT

Author

Matthew Snow -- M2AI | @m2ai-portfolio