From a1d045ad318d92c72f55c59d880299bedfa7229b Mon Sep 17 00:00:00 2001 From: Jonathan Agmon Date: Mon, 23 Mar 2026 17:35:21 +0200 Subject: [PATCH] Add README.md --- README.md | 213 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 213 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..1f9630d --- /dev/null +++ b/README.md @@ -0,0 +1,213 @@ +# gh-celebs + +A fast, non-interactive CLI tool for searching GitHub repositories by popularity (stars). Uses a local SQLite database that learns and grows as you search. + +## Features + +- **Smart Caching**: Searches local database first, only hits GitHub API when needed +- **Popularity-Based**: Results sorted by star count (descending) +- **Dual Output Modes**: Clean plain text (default) or JSON (`--json`) +- **Repository Updates**: Refresh cached repo data with a single command +- **Rate Limit Awareness**: Displays remaining API calls and warns when running low +- **Configurable**: Optional GitHub token for higher rate limits (30 vs 10 calls/minute) +- **Cross-Platform**: Works on Linux, macOS, and Windows + +## Installation + +### From Source + +```bash +git clone https://github.com/yourusername/gh-celebs +cd gh-celebs +cargo build --release +``` + +The binary will be available at `target/release/gh-celebs`. + +### Prerequisites + +- Rust 1.70+ (for building from source) +- GitHub account (optional, for higher API rate limits) + +## Usage + +### Search for Repositories + +```bash +# Search for "react" (default: top 5 results) +gh-celebs react + +# Search with custom limit +gh-celebs react --limit 10 +gh-celebs react -n 10 + +# JSON output for scripting +gh-celebs react --json + +# Combine options +gh-celebs machine learning --limit 20 --json +``` + +### Update Cached Repositories + +```bash +# Update all cached repositories +gh-celebs update + +# Update a specific repository +gh-celebs update facebook/react +``` + +### Help + +```bash +gh-celebs --help +gh-celebs update --help +``` + +## Example Output + +### Plain Text (Default) + +``` +1. facebook/react (220,473 ⭐) - Updated 2026-01-15 + https://github.com/facebook/react + A declarative, efficient, and flexible JavaScript library for building user interfaces. + +2. vuejs/vue (210,123 ⭐) - Updated 2026-01-14 + https://github.com/vuejs/vue + Vue.js is a progressive, incrementally-adoptable JavaScript framework... + +3. vercel/next.js (105,234 ⭐) - Updated 2026-01-16 + https://github.com/vercel/next.js + The React Framework for the Web + +API: [8/10 calls remaining] +``` + +### JSON Output + +```json +{ + "query": "react", + "limit": 5, + "api_remaining": 8, + "api_limit": 10, + "total_cached": 1247, + "results": [ + { + "rank": 1, + "full_name": "facebook/react", + "stars": 220473, + "html_url": "https://github.com/facebook/react", + "description": "A declarative, efficient, and flexible JavaScript library...", + "language": "JavaScript", + "cached_at": "2024-01-15T10:30:00Z" + } + ] +} +``` + +## Configuration + +### Config File Location + +- **Linux**: `~/.config/gh-celebs/config.toml` +- **macOS**: `~/Library/Application Support/com.gh-celebs.gh-celebs/config.toml` +- **Windows**: `%APPDATA%\gh-celebs\gh-celebs\config\config.toml` + +### GitHub Token (Optional) + +Add a GitHub personal access token to increase rate limits from 10 to 30 requests per minute: + +```toml +[github] +token = "ghp_xxxxxxxxxxxxxxxxxxxx" +``` + +To create a token: +1. Go to GitHub → Settings → Developer settings → Personal access tokens +2. Generate a new token (no scopes required for public repo search) +3. Add it to your config file + +### Database Location + +The local SQLite database is stored alongside the config: + +- **Linux**: `~/.local/share/gh-celebs/repos.db` +- **macOS**: `~/Library/Application Support/com.gh-celebs.gh-celebs/repos.db` +- **Windows**: `%APPDATA%\gh-celebs\gh-celebs\data\repos.db` + +## How It Works + +1. **Local Search**: When you run a query, the tool first searches the local SQLite database for cached repositories matching your query (by name or description). + +2. **API Fallback**: If local results are insufficient, the tool queries the GitHub Search API for additional repositories. + +3. **Smart Caching**: API results are automatically cached to the local database for future searches. + +4. **Merging & Sorting**: Local and API results are merged, sorted by star count, and the top N results are returned. + +5. **Updates**: Use the `update` command to refresh star counts and metadata for cached repositories. + +## Rate Limits + +- **Anonymous**: 10 requests per minute +- **Authenticated**: 30 requests per minute (with token) + +The tool displays remaining API calls and warns when running low: + +``` +Warning: Rate limit running low (2 remaining) +``` + +## Tech Stack + +- **Language**: Rust +- **Database**: SQLite (via `rusqlite`) +- **HTTP Client**: `reqwest` (async) +- **CLI**: `clap` (derive-based) +- **Serialization**: `serde` +- **Error Handling**: `anyhow` + +## Project Structure + +``` +gh-celebs/ +├── Cargo.toml +├── README.md +└── src/ + ├── main.rs # Entry point and orchestration + ├── cli.rs # CLI argument definitions + ├── config.rs # Configuration loading + ├── db.rs # Database operations + ├── github.rs # GitHub API client + ├── models.rs # Data structures + ├── output.rs # Output formatters + └── search.rs # Search logic +``` + +## Exit Codes + +- `0` - Success +- `1` - Error (invalid arguments, API errors, etc.) + +## License + +MIT License + +## Contributing + +Contributions are welcome! Please feel free to submit a Pull Request. + +## Future Enhancements + +- [ ] Filter by language (`--lang rust`) +- [ ] Sort options (`--sort updated`, `--sort created`) +- [ ] Export to CSV/JSON file (`--export results.json`) +- [ ] Fuzzy search matching +- [ ] Configurable database location + +## Acknowledgments + +Built with ❤️ using Rust and the GitHub API.