# Changelog Generator 🚀
[](https://badge.fury.io/py/changelog-generator)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
A high-performance, AI-powered command-line tool that generates beautiful changelogs from git commit history using Claude API. Features smart caching, async processing, and seamless GitHub integration.
## ✨ Features
### 🎯 Core Functionality
- **AI-Powered**: Generate professional changelogs using Claude 3.5 Sonnet
- **Multi-Source**: Works with local git repositories and GitHub repositories
- **Beautiful Output**: Rich terminal interface with progress bars and formatted tables
- **Multiple Formats**: Output in Markdown, JSON, or plain text
- **Interactive Mode**: Preview commits before generating changelog
### ⚡ Performance Enhancements
- **Async Processing**: Non-blocking operations for better performance
- **Memory Optimization**: Micro-chunking and garbage collection for large repositories
- **Smart Caching**: Redis-based caching with intelligent freshness detection
- **Rate Limiting**: Intelligent GitHub API rate limiting with token support
- **Connection Pooling**: Efficient HTTP connection management
### 🔗 GitHub Integration
- **Token Authentication**: Automatic GitHub token detection from environment or config
- **Private Repositories**: Support for private repos with proper authentication
- **Rate Limit Handling**: Automatic rate limit detection and backoff
- **Error Recovery**: Robust error handling with automatic retries
## 🚀 Quick Start
### Installation
```bash
# Install from PyPI
pip install changelog-generator
# Or install with development dependencies
pip install changelog-generator[dev]
```
### Basic Usage
```bash
# Generate changelog for last 10 commits (local repository)
changelog-generator 10
# Generate changelog for GitHub repository
changelog-generator 10 --repo owner/repo
# Interactive mode with preview
changelog-generator 10 --interactive
# Save to file
changelog-generator 20 --output changelog.md
# Output as JSON
changelog-generator 15 --format json
```
## 📋 Command Line Options
### Required Arguments
- `num_commits`: Number of recent commits to include in the changelog
### Optional Arguments
- `--repo, -r`: GitHub repository (owner/repo or full URL)
- `--interactive, -i`: Interactive mode with commit preview
- `--output, -o`: Output file path (.md, .txt, .json)
- `--format`: Output format (markdown, text, json)
- `--config`: Show current configuration
- `--api-key`: Override API key
- `--api-url`: Override API base URL
- `--no-cache`: Disable caching
- `--cache-stats`: Show cache statistics
- `--clear-cache`: Clear all cached data
- `--list-repos`: List cached repositories
- `--smart-cache`: Enable smart SHA-based caching (default)
- `--legacy-cache`: Force use of legacy time-based caching
## ⚙️ Configuration
### Environment Variables
```bash
# GitHub token for authenticated requests (recommended)
export GITHUB_TOKEN=ghp_xxxxxxxxxxxx
export GH_TOKEN=ghp_xxxxxxxxxxxx # Alternative
# Optional: Redis configuration
export REDIS_HOST=localhost
export REDIS_PORT=6379
```
### Configuration File
Create `~/.changelog_generator.yaml`:
```yaml
# API Configuration
api_key: "your-api-key-here"
api_url: "https://your-api-endpoint.com"
api_endpoint: "/api/message"
# GitHub Configuration
github:
token: "your-github-token-here"
# Cache Configuration
cache:
enabled: true
max_cached_repos: 50
repo_metadata_ttl: 86400 # 24 hours
commit_data_ttl: 3600 # 1 hour
smart_caching:
enabled: true
sha_check_frequency: 300 # 5 minutes
max_commit_cache_per_repo: 1000
background_updates: true
# Redis Configuration
redis:
host: localhost
port: 6379
db: 0
decode_responses: true
socket_timeout: 5
socket_connect_timeout: 5
```
## 🧠 Smart Caching Features
### SHA-Based Update Detection
- **Precise Detection**: Uses Git-style ahead/behind logic to detect new commits
- **Efficient Updates**: Only fetches new commits when repository has changed
- **Background Monitoring**: Monitors repository state without unnecessary API calls
### Repository Usage Tracking
- **Smart Prioritization**: Frequently used repositories appear first in lists
- **Access Frequency**: Tracks how often repositories are accessed
- **Usage Statistics**: Provides insights into repository usage patterns
### Enhanced Repository Backlog
- **Update Status**: Shows which repositories have new commits
- **Usage Statistics**: Displays access frequency and last accessed time
- **Smart Indicators**: Visual indicators for repository status
## 📊 Examples
### Local Repository
```bash
# Generate changelog for last 15 commits in current directory
changelog-generator 15
```
### GitHub Repository
```bash
# Generate changelog for a public repository
changelog-generator 20 --repo facebook/react
# Generate changelog for a private repository (requires GITHUB_TOKEN)
changelog-generator 10 --repo myorg/private-repo
```
### Interactive Mode
```bash
# Preview commits before generating changelog
changelog-generator 10 --interactive
```
### Save to File
```bash
# Save as Markdown
changelog-generator 25 --output CHANGELOG.md
# Save as JSON
changelog-generator 15 --format json --output changelog.json
```
### Cache Management
```bash
# View cache statistics
changelog-generator 10 --cache-stats
# List cached repositories
changelog-generator 10 --list-repos
# Clear all cached data
changelog-generator 10 --clear-cache
```
## 🔧 Development
### Installation for Development
```bash
# Clone the repository
git clone https://github.com/anantduggal/changelog-generator.git
cd changelog-generator
# Install in development mode
pip install -e .
# Install development dependencies
pip install -e ".[dev]"
```
### Running Tests
```bash
# Run all tests
pytest
# Run with coverage
pytest --cov=changelog_generator
# Run specific test file
pytest tests/test_core.py
```
### Code Quality
```bash
# Format code
black src/ tests/
# Sort imports
isort src/ tests/
# Type checking
mypy src/
# Linting
flake8 src/ tests/
```
## 📦 Package Structure
```
changelog-generator/
├── src/
│ └── changelog_generator/
│ ├── __init__.py
│ └── changelog_generator_enhanced.py
├── tests/
├── pyproject.toml
├── README.md
├── LICENSE
└── CHANGELOG.md
```
## 🤝 Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- [Claude API](https://claude.ai/) for AI-powered changelog generation
- [Rich](https://github.com/Textualize/rich) for beautiful terminal output
- [aiohttp](https://github.com/aio-libs/aiohttp) for async HTTP operations
- [Redis](https://redis.io/) for smart caching functionality
## 📞 Support
- **Issues**: [GitHub Issues](https://github.com/anantduggal/changelog-generator/issues)
- **Documentation**: [GitHub Wiki](https://github.com/anantduggal/changelog-generator/wiki)
- **Email**: aduggal@uwaterloo.ca
---
Made with ❤️ by [Anant Duggal](https://github.com/anantduggal)
Raw data
{
"_id": null,
"home_page": null,
"name": "anantduggal-changelog-generator",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "Anant Duggal <aduggal@uwaterloo.ca>",
"keywords": "ai, changelog, claude, cli, git, github",
"author": null,
"author_email": "Anant Duggal <aduggal@uwaterloo.ca>",
"download_url": "https://files.pythonhosted.org/packages/7f/ee/a9b4a30551b004449d98362272b748d57e1714b1a6ecd8f04c831df3b1ba/anantduggal_changelog_generator-1.0.0.tar.gz",
"platform": null,
"description": "# Changelog Generator \ud83d\ude80\n\n[](https://badge.fury.io/py/changelog-generator)\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n\nA high-performance, AI-powered command-line tool that generates beautiful changelogs from git commit history using Claude API. Features smart caching, async processing, and seamless GitHub integration.\n\n## \u2728 Features\n\n### \ud83c\udfaf Core Functionality\n- **AI-Powered**: Generate professional changelogs using Claude 3.5 Sonnet\n- **Multi-Source**: Works with local git repositories and GitHub repositories\n- **Beautiful Output**: Rich terminal interface with progress bars and formatted tables\n- **Multiple Formats**: Output in Markdown, JSON, or plain text\n- **Interactive Mode**: Preview commits before generating changelog\n\n### \u26a1 Performance Enhancements\n- **Async Processing**: Non-blocking operations for better performance\n- **Memory Optimization**: Micro-chunking and garbage collection for large repositories\n- **Smart Caching**: Redis-based caching with intelligent freshness detection\n- **Rate Limiting**: Intelligent GitHub API rate limiting with token support\n- **Connection Pooling**: Efficient HTTP connection management\n\n### \ud83d\udd17 GitHub Integration\n- **Token Authentication**: Automatic GitHub token detection from environment or config\n- **Private Repositories**: Support for private repos with proper authentication\n- **Rate Limit Handling**: Automatic rate limit detection and backoff\n- **Error Recovery**: Robust error handling with automatic retries\n\n## \ud83d\ude80 Quick Start\n\n### Installation\n\n```bash\n# Install from PyPI\npip install changelog-generator\n\n# Or install with development dependencies\npip install changelog-generator[dev]\n```\n\n### Basic Usage\n\n```bash\n# Generate changelog for last 10 commits (local repository)\nchangelog-generator 10\n\n# Generate changelog for GitHub repository\nchangelog-generator 10 --repo owner/repo\n\n# Interactive mode with preview\nchangelog-generator 10 --interactive\n\n# Save to file\nchangelog-generator 20 --output changelog.md\n\n# Output as JSON\nchangelog-generator 15 --format json\n```\n\n## \ud83d\udccb Command Line Options\n\n### Required Arguments\n- `num_commits`: Number of recent commits to include in the changelog\n\n### Optional Arguments\n- `--repo, -r`: GitHub repository (owner/repo or full URL)\n- `--interactive, -i`: Interactive mode with commit preview\n- `--output, -o`: Output file path (.md, .txt, .json)\n- `--format`: Output format (markdown, text, json)\n- `--config`: Show current configuration\n- `--api-key`: Override API key\n- `--api-url`: Override API base URL\n- `--no-cache`: Disable caching\n- `--cache-stats`: Show cache statistics\n- `--clear-cache`: Clear all cached data\n- `--list-repos`: List cached repositories\n- `--smart-cache`: Enable smart SHA-based caching (default)\n- `--legacy-cache`: Force use of legacy time-based caching\n\n## \u2699\ufe0f Configuration\n\n### Environment Variables\n```bash\n# GitHub token for authenticated requests (recommended)\nexport GITHUB_TOKEN=ghp_xxxxxxxxxxxx\nexport GH_TOKEN=ghp_xxxxxxxxxxxx # Alternative\n\n# Optional: Redis configuration\nexport REDIS_HOST=localhost\nexport REDIS_PORT=6379\n```\n\n### Configuration File\nCreate `~/.changelog_generator.yaml`:\n\n```yaml\n# API Configuration\napi_key: \"your-api-key-here\"\napi_url: \"https://your-api-endpoint.com\"\napi_endpoint: \"/api/message\"\n\n# GitHub Configuration\ngithub:\n token: \"your-github-token-here\"\n\n# Cache Configuration\ncache:\n enabled: true\n max_cached_repos: 50\n repo_metadata_ttl: 86400 # 24 hours\n commit_data_ttl: 3600 # 1 hour\n smart_caching:\n enabled: true\n sha_check_frequency: 300 # 5 minutes\n max_commit_cache_per_repo: 1000\n background_updates: true\n\n# Redis Configuration\nredis:\n host: localhost\n port: 6379\n db: 0\n decode_responses: true\n socket_timeout: 5\n socket_connect_timeout: 5\n```\n\n## \ud83e\udde0 Smart Caching Features\n\n### SHA-Based Update Detection\n- **Precise Detection**: Uses Git-style ahead/behind logic to detect new commits\n- **Efficient Updates**: Only fetches new commits when repository has changed\n- **Background Monitoring**: Monitors repository state without unnecessary API calls\n\n### Repository Usage Tracking\n- **Smart Prioritization**: Frequently used repositories appear first in lists\n- **Access Frequency**: Tracks how often repositories are accessed\n- **Usage Statistics**: Provides insights into repository usage patterns\n\n### Enhanced Repository Backlog\n- **Update Status**: Shows which repositories have new commits\n- **Usage Statistics**: Displays access frequency and last accessed time\n- **Smart Indicators**: Visual indicators for repository status\n\n## \ud83d\udcca Examples\n\n### Local Repository\n```bash\n# Generate changelog for last 15 commits in current directory\nchangelog-generator 15\n```\n\n### GitHub Repository\n```bash\n# Generate changelog for a public repository\nchangelog-generator 20 --repo facebook/react\n\n# Generate changelog for a private repository (requires GITHUB_TOKEN)\nchangelog-generator 10 --repo myorg/private-repo\n```\n\n### Interactive Mode\n```bash\n# Preview commits before generating changelog\nchangelog-generator 10 --interactive\n```\n\n### Save to File\n```bash\n# Save as Markdown\nchangelog-generator 25 --output CHANGELOG.md\n\n# Save as JSON\nchangelog-generator 15 --format json --output changelog.json\n```\n\n### Cache Management\n```bash\n# View cache statistics\nchangelog-generator 10 --cache-stats\n\n# List cached repositories\nchangelog-generator 10 --list-repos\n\n# Clear all cached data\nchangelog-generator 10 --clear-cache\n```\n\n## \ud83d\udd27 Development\n\n### Installation for Development\n```bash\n# Clone the repository\ngit clone https://github.com/anantduggal/changelog-generator.git\ncd changelog-generator\n\n# Install in development mode\npip install -e .\n\n# Install development dependencies\npip install -e \".[dev]\"\n```\n\n### Running Tests\n```bash\n# Run all tests\npytest\n\n# Run with coverage\npytest --cov=changelog_generator\n\n# Run specific test file\npytest tests/test_core.py\n```\n\n### Code Quality\n```bash\n# Format code\nblack src/ tests/\n\n# Sort imports\nisort src/ tests/\n\n# Type checking\nmypy src/\n\n# Linting\nflake8 src/ tests/\n```\n\n## \ud83d\udce6 Package Structure\n\n```\nchangelog-generator/\n\u251c\u2500\u2500 src/\n\u2502 \u2514\u2500\u2500 changelog_generator/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2514\u2500\u2500 changelog_generator_enhanced.py\n\u251c\u2500\u2500 tests/\n\u251c\u2500\u2500 pyproject.toml\n\u251c\u2500\u2500 README.md\n\u251c\u2500\u2500 LICENSE\n\u2514\u2500\u2500 CHANGELOG.md\n```\n\n## \ud83e\udd1d Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \ud83d\ude4f Acknowledgments\n\n- [Claude API](https://claude.ai/) for AI-powered changelog generation\n- [Rich](https://github.com/Textualize/rich) for beautiful terminal output\n- [aiohttp](https://github.com/aio-libs/aiohttp) for async HTTP operations\n- [Redis](https://redis.io/) for smart caching functionality\n\n## \ud83d\udcde Support\n\n- **Issues**: [GitHub Issues](https://github.com/anantduggal/changelog-generator/issues)\n- **Documentation**: [GitHub Wiki](https://github.com/anantduggal/changelog-generator/wiki)\n- **Email**: aduggal@uwaterloo.ca\n\n---\n\nMade with \u2764\ufe0f by [Anant Duggal](https://github.com/anantduggal) ",
"bugtrack_url": null,
"license": "MIT",
"summary": "AI-powered changelog generator with smart caching and async processing",
"version": "1.0.0",
"project_urls": {
"Changelog": "https://github.com/anantduggal/changelog-generator/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/anantduggal/changelog-generator#readme",
"Homepage": "https://github.com/anantduggal/changelog-generator",
"Issues": "https://github.com/anantduggal/changelog-generator/issues",
"Repository": "https://github.com/anantduggal/changelog-generator"
},
"split_keywords": [
"ai",
" changelog",
" claude",
" cli",
" git",
" github"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b207f8545c225110ae3e2e330106a2c4c040f4d3a5ab2b1c6088ed7f37c86fb0",
"md5": "5edd0af178dda9cac375307dd0710afc",
"sha256": "af348b766840199e5bf4aada0054b3e21813f5fadaccba48d1e19533700fb206"
},
"downloads": -1,
"filename": "anantduggal_changelog_generator-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5edd0af178dda9cac375307dd0710afc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 24568,
"upload_time": "2025-07-23T07:32:44",
"upload_time_iso_8601": "2025-07-23T07:32:44.947396Z",
"url": "https://files.pythonhosted.org/packages/b2/07/f8545c225110ae3e2e330106a2c4c040f4d3a5ab2b1c6088ed7f37c86fb0/anantduggal_changelog_generator-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "7feea9b4a30551b004449d98362272b748d57e1714b1a6ecd8f04c831df3b1ba",
"md5": "3b3625d936b11a80730ee16785914e7a",
"sha256": "2efa496e151368a9315858aaffcba46b03b90524ae40c54887321b3bf2881653"
},
"downloads": -1,
"filename": "anantduggal_changelog_generator-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "3b3625d936b11a80730ee16785914e7a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 24058,
"upload_time": "2025-07-23T07:32:46",
"upload_time_iso_8601": "2025-07-23T07:32:46.299031Z",
"url": "https://files.pythonhosted.org/packages/7f/ee/a9b4a30551b004449d98362272b748d57e1714b1a6ecd8f04c831df3b1ba/anantduggal_changelog_generator-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-23 07:32:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "anantduggal",
"github_project": "changelog-generator",
"github_not_found": true,
"lcname": "anantduggal-changelog-generator"
}
JSON
