Add README.md
This commit is contained in:
213
README.md
Normal file
213
README.md
Normal file
@@ -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.
|
||||||
Reference in New Issue
Block a user