> ## Documentation Index
> Fetch the complete documentation index at: https://lunr-f6858e75.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Examples
> Real-world usage examples and patterns for HelixCommit
## Overview
This page provides practical examples of using HelixCommit in various scenarios. Each example includes complete commands and explanations to help you adapt them to your needs.
## Basic examples
### Generate release notes for unreleased changes
The most common use case: see what's changed since your last release.
```bash theme={}
helixcommit generate \
--unreleased \
--format markdown \
--out RELEASE_NOTES.md
```
Works offline with `--no-prs` flag for faster generation.
### Create notes between specific tags
Generate release notes for a specific version range:
```bash theme={}
helixcommit generate \
--since-tag v1.2.0 \
--until-tag v1.2.1 \
--format markdown \
--out release-1.2.1.md
```
### Generate notes for custom commit range
Use commit SHAs or any Git refs:
```bash theme={}
helixcommit generate \
--since abc123def \
--until feature-branch \
--format markdown
```
## Output format examples
### Generate all formats at once
Create release notes in Markdown, HTML, and plain text simultaneously:
```bash theme={}
#!/bin/bash
echo "Generating release notes in all formats..."
# Markdown for GitHub
helixcommit generate \
--unreleased \
--format markdown \
--out RELEASE_NOTES.md
# HTML for website
helixcommit generate \
--unreleased \
--format html \
--out docs/changelog.html
# Text for email
helixcommit generate \
--unreleased \
--format text \
--out CHANGES.txt
echo "✓ Release notes generated in all formats"
```
### Format for specific platforms
```bash theme={}
# Optimized for GitHub releases
helixcommit generate \
--since-tag v1.0.0 \
--until-tag v2.0.0 \
--format markdown \
--include-scopes \
--out RELEASE_NOTES.md
# Use in GitHub CLI
gh release create v2.0.0 \
--title "Version 2.0.0" \
--notes-file RELEASE_NOTES.md
```
```bash theme={}
# Plain text for chat platforms
helixcommit generate \
--unreleased \
--format text \
--no-prs \
--max-items 20 > release.txt
# Post to Slack
curl -X POST https://hooks.slack.com/services/YOUR/WEBHOOK/URL \
-H 'Content-Type: application/json' \
-d "{\"text\": \"$(cat release.txt)\"}"
```
```bash theme={}
# HTML for rich email
helixcommit generate \
--unreleased \
--format html \
--out email_body.html
# Send via email (example with mailx)
cat email_body.html | mail -s "Release Notes v2.0" \
-a "Content-Type: text/html" team@example.com
```
```bash theme={}
# HTML for embedding in website
helixcommit generate \
--since-tag v1.0.0 \
--format html \
--no-merge-commits \
--out public/changelog.html
# Deploy with your site
npm run build
npm run deploy
```
## AI-powered examples
### Basic AI summarization
Generate AI-enhanced release notes with OpenAI:
```bash theme={}
export OPENAI_API_KEY=sk-...
helixcommit generate \
--unreleased \
--use-llm \
--openai-model gpt-4o-mini \
--format markdown \
--out AI_RELEASE_NOTES.md
```
### Free AI with OpenRouter
Use free AI models via OpenRouter:
```bash theme={}
export OPENROUTER_API_KEY=sk-or-...
helixcommit generate \
--unreleased \
--use-llm \
--llm-provider openrouter \
--openrouter-model x-ai/grok-4.1-fast:free \
--format markdown
```
OpenRouter's free tier is perfect for testing AI features without cost.
### Advanced AI with custom prompts
Customize AI behavior for your domain:
```bash theme={}
export OPENAI_API_KEY=sk-...
helixcommit generate \
--unreleased \
--use-llm \
--openai-model gpt-4o-mini \
--domain-scope "healthcare technology" \
--expert-role "Product Manager" \
--expert-role "Clinical Engineer" \
--expert-role "Compliance Officer" \
--rag-backend simple \
--format markdown \
--out RELEASE_NOTES.md
```
## GitHub integration examples
### With full GitHub enrichment
Include pull request information and links:
```bash theme={}
export GITHUB_TOKEN=ghp_...
helixcommit generate \
--unreleased \
--format markdown \
--include-scopes \
--out RELEASE_NOTES.md
```
GitHub integration automatically adds PR links, author information, and compare URLs.
### Offline mode without GitHub
Generate notes without any external API calls:
```bash theme={}
helixcommit generate \
--unreleased \
--no-prs \
--format markdown \
--out RELEASE_NOTES.md
```
### With caching for repeated runs
Enable caching to speed up subsequent runs:
```bash theme={}
export GITHUB_TOKEN=ghp_...
export HELIXCOMMIT_GH_CACHE=1
helixcommit generate \
--unreleased \
--format markdown
```
## Filtering examples
### Exclude merge commits
Create cleaner release notes by excluding merge commits:
```bash theme={}
helixcommit generate \
--unreleased \
--no-merge-commits \
--format markdown
```
### Limit commit count
Process only recent commits for faster generation:
```bash theme={}
helixcommit generate \
--unreleased \
--max-items 50 \
--format markdown
```
### Hide commit scopes
Generate notes without showing commit scopes:
```bash theme={}
helixcommit generate \
--unreleased \
--no-include-scopes \
--format markdown
```
**Output with scopes:**
```
- **api**: Add authentication endpoint
```
**Output without scopes:**
```
- Add authentication endpoint
```
## Programmatic usage
### Python API basic example
Use HelixCommit as a Python library:
```python theme={}
from datetime import datetime
from pathlib import Path
from helixcommit.changelog import ChangelogBuilder
from helixcommit.formatters.markdown import render_markdown
from helixcommit.git_client import CommitRange, GitRepository
# Initialize repository
repo = GitRepository(Path("."))
# Define commit range
commit_range = CommitRange(
since="v1.0.0",
until="v2.0.0",
include_merges=False
)
# Get commits
commits = list(repo.iter_commits(commit_range))
# Build changelog
builder = ChangelogBuilder(include_scopes=True)
changelog = builder.build(
version="v2.0.0",
release_date=datetime.now(),
commits=commits,
commit_prs={},
pr_index={}
)
# Render to markdown
markdown = render_markdown(changelog)
print(markdown)
# Save to file
Path("RELEASE_NOTES.md").write_text(markdown)
```
### With AI summarization
Add AI-powered summaries programmatically:
```python theme={}
from helixcommit.summarizer import PromptEngineeredSummarizer
from pathlib import Path
# Configure AI summarizer
summarizer = PromptEngineeredSummarizer(
api_key="sk-...",
model="gpt-4o-mini",
cache_path=Path(".cache/summaries.json"),
domain_scope="software release notes",
expert_roles=["Product Manager", "Tech Lead"],
rag_backend="simple"
)
# Use with ChangelogBuilder
builder = ChangelogBuilder(
summarizer=summarizer,
include_scopes=True
)
# Build changelog with AI
changelog = builder.build(
version="v2.0.0",
release_date=datetime.now(),
commits=commits,
commit_prs={},
pr_index={}
)
```
### Custom formatter
Create a custom output format:
```python theme={}
from helixcommit.models import Changelog
def custom_formatter(changelog: Changelog) -> str:
"""Custom release notes formatter."""
lines = [f"# Release {changelog.version}"]
lines.append(f"Date: {changelog.date.strftime('%Y-%m-%d') if changelog.date else ''}")
lines.append("")
for section in changelog.sections:
lines.append(f"## {section.title}")
for item in section.items:
lines.append(f"- {item.title}")
lines.append("")
return "\n".join(lines)
# Use custom formatter
output = custom_formatter(changelog)
print(output)
```
## CI/CD integration examples
### GitHub Actions
Automated release notes on tag creation:
```yaml theme={}
name: Generate Release Notes
on:
push:
tags:
- 'v*'
jobs:
release-notes:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
with:
fetch-depth: 0 # Full history for tags
- name: Set up Python
uses: actions/setup-python@v4
with:
python-version: '3.11'
- name: Install HelixCommit
run: pip install helixcommit
- name: Generate release notes
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
helixcommit generate \
--since-tag $(git describe --tags --abbrev=0 HEAD^) \
--until-tag ${{ github.ref_name }} \
--format markdown \
--out RELEASE_NOTES.md
- name: Create GitHub Release
uses: softprops/action-gh-release@v1
with:
body_path: RELEASE_NOTES.md
```
### GitLab CI
```yaml theme={}
generate_release_notes:
stage: release
image: python:3.11
only:
- tags
script:
- pip install helixcommit
- |
helixcommit generate \
--since-tag $CI_COMMIT_BEFORE_SHA \
--until-tag $CI_COMMIT_TAG \
--format markdown \
--out RELEASE_NOTES.md
artifacts:
paths:
- RELEASE_NOTES.md
```
### Jenkins
```groovy theme={}
pipeline {
agent any
stages {
stage('Generate Release Notes') {
steps {
sh '''
pip install helixcommit
helixcommit generate \
--unreleased \
--format markdown \
--out RELEASE_NOTES.md
'''
}
}
stage('Publish') {
steps {
archiveArtifacts artifacts: 'RELEASE_NOTES.md'
}
}
}
}
```
## Shell script examples
### Complete release script
Automated script for creating releases:
```bash theme={}
#!/bin/bash
set -e
# Configuration
NEW_VERSION=$1
PREVIOUS_TAG=$(git describe --tags --abbrev=0)
if [ -z "$NEW_VERSION" ]; then
echo "Usage: $0 "
exit 1
fi
echo "Creating release $NEW_VERSION from $PREVIOUS_TAG"
# Generate release notes
echo "Generating release notes..."
helixcommit generate \
--since-tag "$PREVIOUS_TAG" \
--until HEAD \
--format markdown \
--out "releases/$NEW_VERSION.md"
echo "✓ Release notes: releases/$NEW_VERSION.md"
# Create git tag
git tag -a "$NEW_VERSION" -m "Release $NEW_VERSION"
echo "✓ Created tag $NEW_VERSION"
echo ""
echo "Next steps:"
echo " 1. Review: cat releases/$NEW_VERSION.md"
echo " 2. Push: git push origin $NEW_VERSION"
```
### Weekly changelog script
Generate weekly update summaries:
```bash theme={}
#!/bin/bash
# Get changes from last week
SINCE_DATE="7 days ago"
OUTPUT_FILE="weekly-update-$(date +%Y-%m-%d).md"
echo "Generating weekly update..."
helixcommit generate \
--since "$SINCE_DATE" \
--format markdown \
--no-merge-commits \
--out "$OUTPUT_FILE"
echo "✓ Weekly update: $OUTPUT_FILE"
# Send to team (example)
# cat "$OUTPUT_FILE" | mail -s "Weekly Update" team@example.com
```
## Troubleshooting examples
### Debug mode
Enable verbose output for troubleshooting:
```bash theme={}
# Add debug information
helixcommit --help generate
# Check git repository status
git status
git log --oneline -10
git tag -l
# Verify GitHub token
echo $GITHUB_TOKEN | cut -c1-10
# Test with minimal options
helixcommit generate --format text --max-items 5
```
### Handling edge cases
```bash theme={}
# Empty commits (fail early in CI)
helixcommit generate --unreleased --fail-on-empty || echo "No changes"
# Very large repositories (limit processing)
helixcommit generate --max-items 100 --no-merge-commits
# Repositories without tags
helixcommit generate --since "30 days ago" --format markdown
```
## Next steps
Deep dive into CI/CD automation
Complete programmatic API reference
Advanced configuration options
Full command-line reference