Quick start

Generate your first release notes in under 5 minutes

Estimated time: 5 minutes

Generate release notes in three steps

This guide walks you through installing HelixCommit and generating your first set of release notes.

1. Install HelixCommit

   Install HelixCommit using pip:

   pip install helixcommit
   

   Verify the installation:

   helixcommit --version
   

   You should see the version number displayed, confirming HelixCommit is installed correctly.

2. Navigate to your Git repository

   Change to a directory containing a Git repository with commit history:

   cd /path/to/your/git/repository
   

   If you don’t have a repository handy, you can create a test one or use HelixCommit’s own repository for testing.

   Verify you’re in a Git repository:

   git status
   
3. Generate your release notes

   Run HelixCommit to create release notes for unreleased changes:

   helixcommit generate --unreleased --no-prs --format markdown
   

   You should see structured release notes printed to your terminal, organized by commit type (features, fixes, chores, etc.).

---

Understanding the command

Let’s break down what each option does:

generate · command · required

The main command for generating release notes from Git history.

--unreleased · flag

Generates notes for commits between the latest tag and HEAD. Perfect for previewing what’s changed since your last release.

--no-prs · flag

Skips GitHub API calls to fetch pull request information. Useful for offline work or when you don’t need PR metadata.

--format · string · default: "markdown"

Output format for your release notes. Options: markdown, html, or text.

---

Save output to a file

To save your release notes instead of printing them to the terminal:

helixcommit generate \
  --unreleased \
  --format markdown \
  --out RELEASE_NOTES.md

The --out option writes the generated content to a file. The directory will be created automatically if it doesn’t exist.

---

Generate notes between specific tags

To create release notes for a specific version range:

helixcommit generate \
  --since-tag v1.2.0 \
  --until-tag v1.2.1 \
  --format markdown \
  --out v1.2.1-release-notes.md

This generates notes for all commits between the two tags.

---

Common use cases

Unreleased changes

Preview what’s changed since your last release:

helixcommit generate --unreleased --format markdown

Perfect for reviewing changes before creating a new release.

Specific version

Generate notes for a specific tagged version:

helixcommit generate \
  --since-tag v2.0.0 \
  --until-tag v2.1.0 \
  --format html \
  --out release-2.1.0.html

Ideal for creating release documentation when cutting a new version.

With GitHub enrichment

Include pull request information and GitHub links:

export GITHUB_TOKEN=your_github_token

helixcommit generate \
  --unreleased \
  --format markdown \
  --out RELEASE_NOTES.md

Create a GitHub token at github.com/settings/tokens with repo scope for private repositories.

Custom commit range

Generate notes for any commit range using refs:

helixcommit generate \
  --since abc123 \
  --until def456 \
  --format text

Works with commit SHAs, branches, or any Git ref.

---

Example output

Here’s what HelixCommit output looks like:

## Release
_Released on 2025-11-13_

### Features
- Add support for custom templates (a1b2c3d)
- Implement AI summarization with caching (e4f5g6h)

### Bug Fixes
- Fix rate limiting handling in GitHub client (i7j8k9l)
- Resolve parsing error for merge commits (m0n1o2p)

### Chores
- Update dependencies to latest versions (q3r4s5t)
- Improve test coverage for formatters (u6v7w8x)

HelixCommit automatically categorizes commits based on Conventional Commits format (feat:, fix:, chore:, etc.).

---

Verify your output

Check commit categorization

HelixCommit groups commits by type. Verify that:

• Features are under Features
• Bug fixes are under Bug Fixes
• Documentation changes are under Documentation
• Other changes are appropriately categorized

If commits aren’t categorized correctly, ensure they follow Conventional Commits format.

Validate HTML output

When generating HTML output:

helixcommit generate --unreleased --format html --out release.html

Open release.html in a browser to verify formatting and styling.

Test with different date ranges

Try generating notes for different ranges to ensure accuracy:

# Last week's changes
helixcommit generate --since "7 days ago" --format markdown

# Specific commit range
helixcommit generate --since abc123 --until def456 --format markdown

---

Next steps

Now that you’ve generated your first release notes, explore more advanced features:

CLI reference

Explore all available commands and options

Configuration

Customize HelixCommit for your workflow

AI features

Enable AI-powered summaries for better release notes

Examples

See real-world usage examples and patterns

---

Troubleshooting

No commits found

If HelixCommit reports no commits:

1. Verify you’re in a Git repository: git status
2. Check that you have commits: git log
3. If using tags, verify they exist: git tag -l
4. Try without filtering: helixcommit generate --format markdown

Permission denied errors

If you see GitHub API permission errors:

1. Set a GitHub token: export GITHUB_TOKEN=your_token
2. Or skip PR lookups: --no-prs flag
3. Verify token has correct permissions at github.com/settings/tokens

Empty or unexpected output

If output is empty or unexpected:

1. Check commit message format follows Conventional Commits
2. Verify the commit range contains commits: git log --oneline
3. Try increasing verbosity with --max-items 100 to process more commits
4. Review excluded merge commits with --no-merge-commits flag removed

Need more help? Check out the full documentation or visit our GitHub repository to open an issue.