github-smart-checkout

Find the newest GitHub release with positive reactions, and optionally checkout that release.

Overview

This tool queries the GitHub API for releases of a repository, analyzes reaction counts to find releases with positive feedback, and helps you checkout the newest qualifying release.

Positive reactions include: +1, heart, and hooray. Negative reactions: -1.

It's designed for projects like llama.cpp where releases are reaction-voted and you want to find stable, well-received versions.

Installation

pip install requests

Or clone the repository:

git clone <repository-url>
cd github-smart-checkout

Usage

Basic Usage

python release_finder.py ggml-org/llama.cpp

This finds the newest release with more positive than negative reactions and displays its information.

Checkout a Release

python release_finder.py ggml-org/llama.cpp --checkout

This will automatically checkout the found release in your current git repository.

CLI Arguments

Argument	Type	Default	Description
repo	string	ggml-org/llama.cpp	Repository in owner/repo format
--min-likes	int	1	Minimum number of positive reactions (+1/heart/hooray) required
--max-dislikes	int	10	Maximum number of negative reactions (-1) allowed (set to -1 for no limit)
--min-like-ratio	float	0.8	Minimum like ratio (positive / (positive + negative)) (0.0 to 1.0, e.g., 0.8 for 80%)
--min-age-hours	float	0.0	Minimum age of release in hours
--min-downloads	int	0	Minimum download count
--allow-prerelease	flag	false	Include pre-release releases in search
--checkout	flag	false	Automatically checkout the release
--allow-downgrade	flag	false	Allow checking out an older release (downgrade)

Filtering Criteria

A release must meet all of the following to be considered valid:

1. Minimum likes: At least --min-likes positive reactions (+1/heart/hooray) (default: 1)
2. Maximum dislikes: No more than --max-dislikes negative reactions (-1) (default: 10)
3. Like ratio: Positive / (positive + negative) >= --min-like-ratio (default: 0.8)
4. Minimum age: Release must be at least --min-age-hours hours old (default: 0, no minimum)
5. Minimum downloads: At least --min-downloads total downloads (default: 0)

Examples

Find releases with at least 10 positive reactions and 80% positive ratio

python release_finder.py ggml-org/llama.cpp --min-likes 10 --min-like-ratio 0.8

Find stable releases (older than 24 hours) with 100+ downloads

python release_finder.py ggml-org/llama.cpp --min-age-hours 24 --min-downloads 100

Allow prereleases and downgrades

python release_finder.py ggml-org/llama.cpp --allow-prerelease --allow-downgrade --checkout

Check out the release automatically

cd /path/to/your/git/repo
python release_finder.py ggml-org/llama.cpp --checkout

Checkout and build workflow

cd /path/to/your/git/repo
python release_finder.py --checkout && ./build.sh

Exit Codes

• 0: Success (new release checked out or found)
• 1: Failure (no release found, checkout failed, or not in a git repository)

API Usage

The tool uses the GitHub REST API:

• GET /repos/{owner}/{repo}/releases - Fetch releases
• Reactions are included in the response body

Rate limits apply (60 requests/hour unauthenticated, 5000/hour with token).

Reaction Types

GitHub provides the following reaction types for releases:

Type	Category	Description
+1	Positive	Thumbs up
heart	Positive	Heart
hooray	Positive	Confetti
laugh	Neutral	Laugh (not counted)
eyes	Neutral	Eyes (not counted)
confused	Neutral	Confused (not counted)
-1	Negative	Thumbs down

Only +1, heart, and hooray are counted as positive reactions. Only -1 is counted as negative.

How It Works

1. Fetches all releases from the GitHub API
2. Iterates through releases (newest first)
3. Counts positive reactions (+1, heart, hooray) and negative reactions (-1)
4. For each release, checks if it meets all filter criteria
5. Returns the first (newest) release that passes all filters
6. If --checkout is specified, performs a git checkout of the release tag