mirror of
https://github.com/ivuorinen/dotfiles.git
synced 2026-03-19 00:06:20 +00:00
feat(bin): x-gh-get-latest-version improvements
This commit is contained in:
196
local/bin/x-gh-get-latest-version.md
Normal file
196
local/bin/x-gh-get-latest-version.md
Normal file
@@ -0,0 +1,196 @@
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
export GITHUB_TOKEN="your_personal_access_token"
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
```text
|
||||
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
|
||||
|
||||
```bash
|
||||
x-gh-get-latest-version ivuorinen/dotfiles
|
||||
```
|
||||
|
||||
Output: `v1.2.3`
|
||||
|
||||
### Include Prereleases
|
||||
|
||||
```bash
|
||||
x-gh-get-latest-version ivuorinen/dotfiles --prereleases
|
||||
```
|
||||
|
||||
Output: `v1.3.0-rc.1`
|
||||
|
||||
### Get the Oldest Release
|
||||
|
||||
```bash
|
||||
x-gh-get-latest-version ivuorinen/dotfiles --oldest
|
||||
```
|
||||
|
||||
Output: `v0.1.0`
|
||||
|
||||
### Fetch from a Specific Branch
|
||||
|
||||
```bash
|
||||
x-gh-get-latest-version ivuorinen/dotfiles --branch develop
|
||||
```
|
||||
|
||||
Output: `develop-v1.3.0`
|
||||
|
||||
### Get Latest Commit SHA
|
||||
|
||||
```bash
|
||||
x-gh-get-latest-version ivuorinen/dotfiles --commit
|
||||
```
|
||||
|
||||
Output: `a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0`
|
||||
|
||||
### Fetch Latest Git Tag
|
||||
|
||||
```bash
|
||||
x-gh-get-latest-version ivuorinen/dotfiles --tag
|
||||
```
|
||||
|
||||
Output: `v2.0.0-beta.1`
|
||||
|
||||
### Output as JSON
|
||||
|
||||
```bash
|
||||
x-gh-get-latest-version ivuorinen/dotfiles --json
|
||||
```
|
||||
|
||||
Output: `{"repository": "ivuorinen/dotfiles", "result": "v1.2.3"}`
|
||||
|
||||
### Combined Information Output
|
||||
|
||||
```bash
|
||||
x-gh-get-latest-version ivuorinen/dotfiles --all
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```text
|
||||
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
|
||||
|
||||
```bash
|
||||
x-gh-get-latest-version ivuorinen/dotfiles --all --json
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
{
|
||||
"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:
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->
|
||||
Reference in New Issue
Block a user