| --- |
| license: mit |
| language: |
| - en |
| pipeline_tag: text-classification |
| --- |
| # git-commits-sorter |
|
|
| Classify raw git commit messages into categories (`bugfix`, `feature`, `chore`, `docs`, `refactor`, etc.) using a hybrid ML pipeline: TF-IDF + metadata → SVM / RF / CatBoost. |
|
|
| ## Features |
|
|
| - **Hybrid model** — combines TF-IDF on the message text with numeric features (files changed, additions, deletions, test/doc/src counts) and categorical features (file extensions, directories) |
| - **Multiple classifiers** — LinearSVC, LogisticRegression, RandomForest, CatBoost, XGBoost |
| - **CPU & GPU** — `--gpu` flag enables cuML / CatBoost GPU / XGBoost GPU automatically |
| - **Auto-labeled dataset** — 83% of raw commits automatically labeled via conventional commit prefixes, gitmoji, and keyword heuristics |
| - **Resumable scraping** — GitHub commit scraper with exponential backoff, progress persistence, and connection error resilience |
|
|
| ## Pipeline |
|
|
| ``` |
| parser.py → GitHub API → commits.jsonl (resilient scraping) |
| build_dataset.py → commits.jsonl → dataset.jsonl (auto-label + feature extraction) |
| train.py → dataset.jsonl → model.joblib (train & save) |
| predict.py → model.joblib → label (inference CLI) |
| commitsorter.py → CommitClassifier class (library API) |
| ``` |
|
|
| ## Usage |
|
|
| ### CLI |
|
|
| ```bash |
| # single prediction |
| python predict.py "fix broad phase crash" 3 45 12 |
| |
| # positional args: message [files_count] [additions] [deletions] |
| python predict.py "bump lodash to 2.1" |
| |
| # batch via stdin |
| echo '{"text":"fix crash","files_count":2} |
| {"text":"add login page","files_count":5,"additions":200}' | python predict.py --stdin |
| ``` |
|
|
| ### Library |
|
|
| ```python |
| from commitsorter import CommitClassifier |
| |
| clf = CommitClassifier("model.joblib") |
| |
| label, scores = clf.sort("fix renderer crash", files_count=2, additions=10) |
| # → ("bugfix", [("bugfix", 0.77), ("chore", 0.11), ...]) |
| |
| results = clf.sort_batch([ |
| {"text": "update dependencies", "files_count": 1}, |
| {"text": "add user auth", "files_count": 5, "additions": 200}, |
| ]) |
| ``` |
|
|
| ### Training |
|
|
| ```bash |
| # single model (default: SVM) |
| python train.py svm |
| python train.py lr |
| python train.py rf |
| python train.py cb |
| python train.py xgb |
| |
| # tournament — compare all models |
| python train.py --all |
| |
| # GPU acceleration (requires cuML / CUDA) |
| python train.py svm --gpu |
| python train.py --all --gpu |
| ``` |
|
|
| ## Dataset features |
|
|
| Each training sample: |
|
|
| | Field | Type | Description | |
| |---|---|---| |
| | `text` | string | Commit message (prefix stripped) | |
| | `files_count` | int | Number of files changed | |
| | `additions` | int | Lines added | |
| | `deletions` | int | Lines deleted | |
| | `changed_tests` | int | Test files touched | |
| | `changed_docs` | int | Doc files touched | |
| | `changed_source` | int | Source files touched | |
| | `has_tests` | bool | Any file in a test directory | |
| | `has_docs` | bool | Any file in a docs directory | |
| | `extensions` | [string] | Unique file extensions | |
| | `directories` | [string] | Unique top-level directories | |
| | `label` | string | Target class | |
|
|
| ## Model: TF-IDF + metadata |
|
|
| ``` |
| commit message ──→ TF-IDF(10k unigrams+bigrams) |
| file metadata ──→ StandardScaler |
| extensions ──→ OneHotEncoder |
| directories ──→ OneHotEncoder |
| ↓ |
| ColumnTransformer |
| ↓ |
| LinearSVC / RF / CatBoost / XGBoost |
| ``` |
|
|
| Best result: **LinearSVC at 79% accuracy** on held-out test set. |
|
|
| ## Supported labels |
|
|
| | Label | Heuristics | |
| |---|---| |
| | `bugfix` | `fix:`, `:bug:`, "crash", "prevent" | |
| | `feature` | `feat:`, `:sparkles:`, "add", "implement" | |
| | `chore` | `chore:`, "bump", "update", "lint" | |
| | `docs` | `docs:`, file-only docs/, `.md` | |
| | `refactor` | `refactor:`, "cleanup", "remove", "rename" | |
| | `test` | `test:`, file-only spec/ or test/ | |
| | `build` | `build:`, "upgrade", dependency changes | |
| | `ci` | `ci:`, CI config changes | |
| | `perf` | `perf:`, "optimize" | |
| | `style` | `style:`, "format", "prettier" | |
| | `revert` | `revert:` | |
|
|
| ## Data scraping |
|
|
| ```bash |
| # needs GITHUB_TOKEN in .env |
| python parser.py |
| ``` |
|
|
| Collects commits from configured repos into `commits.jsonl`. Resumes on interrupt via `progress.json`. |
