git-brief

AI-powered GitHub Repository Summarizer — point it at any public GitHub repo and get a concise, professional Markdown summary in seconds.

---

Features

• Fetches repo description, language, full file tree, and README via the GitHub REST API
• Summarizes with Google Gemini: purpose, features, tech stack, structure & quick start
• Rich CLI with live spinners, colour output, and pretty Markdown rendering
• Save to file with --output summary.md
• Secure key management via .env / environment variables

---

Quick Start

1. Clone & Install

git clone https://github.com/<you>/git-brief.git
cd git-brief
pip install -r requirements.txt

2. Configure API Keys

cp .env.example .env
# Open .env and fill in your keys (see below)

Variable	Required	Description
GEMINI_API_KEY	Yes	Get one here
GITHUB_TOKEN	Optional	Raises GitHub rate limit 60 → 5 000 req/h

3. Run

# Print summary to terminal
python main.py --url https://github.com/tiangolo/fastapi

# Save summary to a file
python main.py --url https://github.com/psf/requests --output summary.md

# With an explicit GitHub token
python main.py --url https://github.com/owner/private-repo --token ghp_xxxx

---

Project Structure

git-brief/
├── main.py            # CLI entry point (Typer + Rich)
├── github_client.py   # GitHub REST API client
├── summarizer.py      # Google Gemini AI integration
├── requirements.txt   # Python dependencies
├── .env.example       # API key template
└── README.md

---

CLI Options

Flag	Short	Default	Description
--url	-u	required	GitHub repository URL
--token	-t	$GITHUB_TOKEN	GitHub Personal Access Token
--output	-o	(stdout)	Write Markdown to this file
--help			Show help and exit

---

Dependencies

Package	Purpose
requests	GitHub REST API calls
python-dotenv	.env file loading
google-generativeai	Gemini LLM integration
typer	CLI framework
rich	Terminal formatting & spinners

---

Error Handling

Situation	Behaviour
Invalid URL format	Clear error message + exit code 1
Repository not found	"Not found" message + exit code 1
Private repo (no token)	"Access denied" message + exit code 1
Missing GEMINI_API_KEY	Configuration error message + exit code 1
Gemini API failure	"AI error" message + exit code 1

---

License

MIT