ReadMine

A Python tool to fetch, cache, and analyze trending GitHub repositories with README support.

Features

• Fetch trending repositories from GitHub (daily, weekly, monthly)
• Automatically download and cache README files
• Support for both .md and .rst README formats
• Color-coded terminal output with emoji indicators
• Smart README detection across multiple branches and paths
• Verbose mode for debugging and detailed information
• Local cache to minimize network requests

Installation

1. Clone the repository:

   git clone https://github.com/yourusername/readmine.git
   cd readmine

2. Create and activate a virtual environment (recommended):

   python -m venv venv
   source venv/bin/activate  # On Windows use: venv\Scripts\activate

3. Install the required dependencies:

   pip install -r requirements.txt

Usage

Basic Usage

# Show trending repositories (default: daily)
python -m readmine.readmine

# Enable verbose output
python -m readmine.readmine --verbose

Output Format

Each repository is displayed with the following format:

● 🔥 m#1 2025-07-10 21:51 MD user/repo
│   │    │        └─ README timestamp (if available)
│   │    └─ Time period (d=day, w=week, m=month)
│   └─ Rank
└─ Status indicator (● = new, ○ = seen before)

Status Indicators:

• 🔥 - Recently updated (within 24 hours)
• 💨 - Not recently updated
• MD/RST - README format (green if exists, yellow if missing)
• R in red - No main/master branch found
• R in yellow - Branch exists but no README found

How It Works

1. Fetching Trends: Uses web scraping to get trending repositories from GitHub
2. README Caching:
   • Checks local cache first (readmes/ directory)
   • Falls back to remote fetch if not found locally
   • Supports multiple branches (main, master, gh-pages)
   • Tries multiple paths and filename variations
3. Output:
   • Color-coded terminal output
   • Summary of new/unique repositories
   • Count of missing READMEs

Requirements

• Python 3.7+
• requests
• beautifulsoup4
• lxml

Command Line Options

• --verbose, -v: Enable verbose output for debugging

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.