dotfiles/local/bin/x-gh-get-latest-version.md

GitHub Latest Version Fetcher

x-gh-get-latest-version is a versatile command-line tool for fetching the latest version information from GitHub repositories. It can retrieve release versions, Git tags, branch tags, and commit SHAs with simple commands.

Features

• Fetch latest or oldest stable releases
• Include prerelease versions
• Get latest Git tags from any branch
• Fetch latest commit SHA from a specific branch
• Output in plain text or JSON format
• Combined output mode to get all information at once
• Rate limit checking to avoid GitHub API throttling
• Authenticated requests with GitHub token support

Requirements

• curl for making HTTP requests
• jq for processing JSON responses
• A GitHub personal access token (optional, but recommended to avoid rate limiting)

Installation

1. Save the script to a location in your PATH
2. Make it executable: chmod +x x-gh-get-latest-version
3. Optionally set up a GitHub token as an environment variable:

export GITHUB_TOKEN="your_personal_access_token"

Usage

Usage: x-gh-get-latest-version <repo> [options]

Arguments:
  <repo>                   Repository in format 'owner/repo' (e.g. ivuorinen/dotfiles)

Options:
  -h, --help               Show this help message and exit
  -v, --verbose            Enable verbose output
  -p, --prereleases        Include prerelease versions (default: only stable releases)
  -o, --oldest             Fetch the oldest release instead of the latest
  -b, --branch <branch>    Fetch the latest tag from a specific branch (default: main)
  -c, --commit             Fetch the latest commit SHA from the specified branch
  -t, --tag                Fetch the latest Git tag (any branch)
  -j, --json               Return output as JSON (default: plain text)
  -a, --all                Fetch all information types in a combined output

Examples

Fetch the Latest Release Version

x-gh-get-latest-version ivuorinen/dotfiles

Output: v1.2.3

Include Prereleases

x-gh-get-latest-version ivuorinen/dotfiles --prereleases

Output: v1.3.0-rc.1

Get the Oldest Release

x-gh-get-latest-version ivuorinen/dotfiles --oldest

Output: v0.1.0

Fetch from a Specific Branch

x-gh-get-latest-version ivuorinen/dotfiles --branch develop

Output: develop-v1.3.0

Get Latest Commit SHA

x-gh-get-latest-version ivuorinen/dotfiles --commit

Output: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0

Fetch Latest Git Tag

x-gh-get-latest-version ivuorinen/dotfiles --tag

Output: v2.0.0-beta.1

Output as JSON

x-gh-get-latest-version ivuorinen/dotfiles --json

Output: {"repository": "ivuorinen/dotfiles", "result": "v1.2.3"}

Combined Information Output

x-gh-get-latest-version ivuorinen/dotfiles --all

Output:

Repository: ivuorinen/dotfiles
Branch:     main
Git Tag:    v2.0.0-beta.1
Commit:     a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0
Prerelease: v1.3.0-rc.1
Release:    v1.2.3

Combined Output as JSON

x-gh-get-latest-version ivuorinen/dotfiles --all --json

Output:

{
  "repository": "ivuorinen/dotfiles",
  "branch": "main",
  "tag": "v2.0.0-beta.1",
  "commit": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0",
  "prerelease": "v1.3.0-rc.1",
  "release": "v1.2.3"
}

Environment Variables

You can use environment variables instead of command-line options:

• INCLUDE_PRERELEASES=1 - Include prerelease versions
• OLDEST_RELEASE=1 - Fetch the oldest release instead of the latest
• BRANCH=branch_name - Specify a branch to fetch tags from
• LATEST_COMMIT=1 - Fetch latest commit SHA
• LATEST_TAG=1 - Fetch latest Git tag
• OUTPUT=json - Output results as JSON
• GITHUB_API_URL=url - Override GitHub API URL (useful for GitHub Enterprise)
• GITHUB_TOKEN=token - Use GitHub API token to increase rate limits
• VERBOSE=1 - Enable verbose output

GitHub API Rate Limits

GitHub enforces rate limits on API requests:

• Unauthenticated requests: 60 requests per hour
• Authenticated requests: 5,000 requests per hour

For frequent use, it's strongly recommended to set up a GitHub token:

export GITHUB_TOKEN="your_personal_access_token"

The script will automatically warn you when you're approaching your rate limit and suggest using a token if you haven't already.

Error Handling

The script provides informative error messages for common issues:

• Repository not found
• Rate limit exceeded
• No releases/tags found
• Invalid arguments

Author

Ismo Vuorinen (https://github.com/ivuorinen)

License

MIT