# Auto Changelog Generator

[![CI](https://7000pct.gitea.bloupla.net/7000pctAUTO/auto-changelog-generator/actions/workflows/ci.yml/badge.svg)](https://7000pct.gitea.bloupla.net/7000pctAUTO/auto-changelog-generator/actions)
[![Version](https://img.shields.io/pypi/v/changeloggen.svg)](https://pypi.org/project/changeloggen/)
[![Python](https://img.shields.io/pypi/pyversions/changeloggen.svg)](https://pypi.org/project/changeloggen/)
[![License](https://img.shields.io/pypi/l/ch/changeloggen.svg)](https://opensource.org/licenses/MIT)

A Python CLI tool that automatically generates changelogs from git diffs and staged changes using local AI models. Categorizes changes (feat, fix, docs, breaking), groups related changes, and produces human-readable release summaries following the Conventional Commits format.

## Features

- **Git Diff Analysis**: Analyze staged and unstaged changes from git repositories
- **AI Categorization**: Categorize changes using local LLM models (Ollama/LM Studio)
- **Conventional Changelog**: Generate markdown changelogs following Conventional Commits specification
- **Multiple Output Formats**: Support for markdown, JSON, and GitHub/GitLab release notes
- **Git Hook Integration**: Install hooks for automatic changelog generation on commits
- **Configuration**: YAML-based configuration with environment variable overrides

## Installation

### From Source

```bash
# Clone the repository
git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/auto-changelog-generator.git
cd auto-changelog-generator

# Install dependencies
pip install -e .

# Or install with dev dependencies
pip install -e ".[dev]"
```

### Using pip

```bash
pip install changeloggen
```

### Dependencies

- Python 3.10+
- GitPython >= 3.1.40
- Typer >= 0.9.0
- Rich >= 13.7.0
- Pydantic >= 2.5.0
- Requests >= 2.31.0
- PyYAML >= 6.0.1

## Quick Start

### Basic Usage

Generate a changelog from staged changes:

```bash
changeloggen generate
```

Generate with a specific model:

```bash
changeloggen generate --model llama3.2
```

Include unstaged changes:

```bash
changeloggen generate --all
```

### Output Formats

Markdown changelog (default):

```bash
changeloggen generate --output markdown
```

JSON output for programmatic consumption:

```bash
changeloggen generate --output json
```

GitHub/GitLab release notes:

```bash
changeloggen generate --output release
```

### Generate Release Notes

Create release notes for a version:

```bash
changeloggen release --version 1.0.0
```

## Configuration

### Configuration File

Create a `.changeloggen.yaml` file in your project root:

```yaml
ollama_url: http://localhost:11434
model: llama3.2
temperature: 0.3
output_format: markdown
include_unstaged: false
```

Or in `~/.config/changeloggen/config.yaml` for user-wide settings.

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `CHANGELOGGEN_OLLAMA_URL` | LLM API URL | http://localhost:11434 |
| `CHANGELOGGEN_MODEL` | Model name | llama3.2 |
| `CHANGELOGGEN_CONFIG` | Config file path | - |
| `CHANGELOGGEN_NO_COLOR` | Disable colors | - |

### Commands

#### generate

Generate changelog from git diffs.

```bash
changeloggen generate [OPTIONS]
```

Options:
- `--output, -o`: Output format (markdown, json, release, commit-message)
- `--model, -m`: LLM model to use
- `--all, -a`: Include unstaged changes
- `--version, -v`: Version string for changelog
- `--output-file, -f`: Write output to file

#### release

Generate release notes for GitHub/GitLab.

```bash
changeloggen release [OPTIONS]
```

Options:
- `--version, -v`: Version for release notes
- `--output-file, -f`: Write output to file
- `--model, -m`: LLM model to use

#### install-hook

Install git hooks for automatic changelog generation.

```bash
changeloggen install-hook <hook-type> [OPTIONS]
```

Options:
- `--model, -m`: LLM model to use
- `--branches, -b`: Comma-separated branches to run on

Hook types:
- `prepare-commit-msg`: Run before commit message editor
- `commit-msg`: Run after commit message is written

#### remove-hook

Remove installed git hook.

```bash
changeloggen remove-hook <hook-type>
```

#### list-hooks

List all installed changeloggen hooks.

```bash
changeloggen list-hooks
```

#### config

Manage configuration.

```bash
# Show current configuration
changeloggen config show

# Update configuration
changeloggen config set --model custom-model --temperature 0.5
```

#### check

Check system requirements and connectivity.

```bash
changeloggen check
```

#### version

Show version information.

```bash
changeloggen version
```

## Git Hook Integration

### Install Hooks

Install prepare-commit-msg hook for all branches:

```bash
changeloggen install-hook prepare-commit-msg --model llama3.2
```

Install for specific branches only:

```bash
changeloggen install-hook prepare-commit-msg --branches main,develop
```

### Remove Hooks

```bash
changeloggen remove-hook prepare-commit-msg
```

## Output Formats

### Markdown Changelog

```markdown
# Changelog v1.0.0 (2024-01-15)

## ✨ Features
- **feat(auth):** add user login functionality

## 🐛 Bug Fixes
- **fix(api):** fix memory leak in connection pool

## 📝 Documentation
- **docs(readme):** update installation instructions

---

### Summary
This release adds user authentication, fixes a memory leak, and updates documentation.
```

### JSON Output

```json
{
  "version": "1.0.0",
  "generated_at": "2024-01-15T10:30:00Z",
  "summary": "This release adds user authentication.",
  "changes": [
    {
      "type": "feat",
      "scope": "auth",
      "description": "add user login functionality",
      "file_path": "src/auth/login.py",
      "breaking_change": false,
      "confidence": 0.95
    }
  ],
  "breaking_changes": [],
  "contributors": ["@developer1"]
}
```

### Release Notes

```markdown
## Release v1.0.0

### ✨ Features
- **(auth)** add user login functionality

### 🐛 Bug Fixes
- **(api)** fix memory leak in connection pool

### Contributors
Thank you to our contributors:
- @developer1
- @developer2

---
**This release adds user authentication and fixes a memory leak.**
```

## Development

### Running Tests

```bash
# Run all tests
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=src/changeloggen --cov-report=term-missing
```

### Linting

```bash
# Check code style
ruff check src/changeloggen/

# Auto-fix issues
ruff check src/changeloggen/ --fix
```

### Type Checking

```bash
mypy src/changeloggen/ --strict
```

## Requirements

- **Git**: Must be installed and available in PATH
- **Local LLM**: Ollama or LM Studio running with REST API
- **Python**: 3.10 or higher

### LLM Server Setup

#### Ollama

```bash
# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# Start Ollama
ollama serve

# Pull a model
ollama pull llama3.2
```

#### LM Studio

1. Download LM Studio from https://lmstudio.ai
2. Start the local server
3. Load a model

## Error Handling

| Error | Solution |
|-------|----------|
| Git repo not found | Initialize git: `git init` |
| No staged changes | Stage files: `git add <files>` |
| LLM not running | Start Ollama/LM Studio |
| Invalid config file | Validate YAML syntax |
| API connection failed | Check LLM server URL |

## Contributing

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

## License

This project is licensed under the MIT License - see the LICENSE file for details.