> ## 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.

# Quick start

> Generate your first release notes in under 5 minutes

<Info>
  **Estimated time:** 5 minutes
</Info>

## Generate release notes in three steps

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

<Steps>
  <Step title="Install HelixCommit" icon="download">
    Install HelixCommit using pip:

    ```bash theme={}
    pip install helixcommit
    ```

    Verify the installation:

    ```bash theme={}
    helixcommit --version
    ```

    <Check>
      You should see the version number displayed, confirming HelixCommit is installed correctly.
    </Check>
  </Step>

  <Step title="Navigate to your Git repository" icon="folder-open">
    Change to a directory containing a Git repository with commit history:

    ```bash theme={}
    cd /path/to/your/git/repository
    ```

    <Tip>
      If you don't have a repository handy, you can create a test one or use HelixCommit's own repository for testing.
    </Tip>

    Verify you're in a Git repository:

    ```bash theme={}
    git status
    ```
  </Step>

  <Step title="Generate your release notes" icon="play">
    Run HelixCommit to create release notes for unreleased changes:

    ```bash theme={}
    helixcommit generate --unreleased --no-prs --format markdown
    ```

    <Check>
      You should see structured release notes printed to your terminal, organized by commit type (features, fixes, chores, etc.).
    </Check>
  </Step>
</Steps>

***

## Understanding the command

Let's break down what each option does:

<ParamField path="generate" type="command" required>
  The main command for generating release notes from Git history.
</ParamField>

<ParamField query="--unreleased" type="flag">
  Generates notes for commits between the latest tag and HEAD. Perfect for previewing what's changed since your last release.
</ParamField>

<ParamField query="--no-prs" type="flag">
  Skips GitHub API calls to fetch pull request information. Useful for offline work or when you don't need PR metadata.
</ParamField>

<ParamField query="--format" type="string" default="markdown">
  Output format for your release notes. Options: `markdown`, `html`, or `text`.
</ParamField>

***

## Save output to a file

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

```bash theme={}
helixcommit generate \
  --unreleased \
  --format markdown \
  --out RELEASE_NOTES.md
```

<Info>
  The `--out` option writes the generated content to a file. The directory will be created automatically if it doesn't exist.
</Info>

***

## Generate notes between specific tags

To create release notes for a specific version range:

```bash theme={}
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

<Tabs>
  <Tab title="Unreleased changes">
    Preview what's changed since your last release:

    ```bash theme={}
    helixcommit generate --unreleased --format markdown
    ```

    Perfect for reviewing changes before creating a new release.
  </Tab>

  <Tab title="Specific version">
    Generate notes for a specific tagged version:

    ```bash theme={}
    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.
  </Tab>

  <Tab title="With GitHub enrichment">
    Include pull request information and GitHub links:

    ```bash theme={}
    export GITHUB_TOKEN=your_github_token

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

    <Note>
      Create a GitHub token at [github.com/settings/tokens](https://github.com/settings/tokens) with `repo` scope for private repositories.
    </Note>
  </Tab>

  <Tab title="Custom commit range">
    Generate notes for any commit range using refs:

    ```bash theme={}
    helixcommit generate \
      --since abc123 \
      --until def456 \
      --format text
    ```

    Works with commit SHAs, branches, or any Git ref.
  </Tab>
</Tabs>

***

## Example output

Here's what HelixCommit output looks like:

<Frame>
  ```markdown theme={}
  ## 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)
  ```
</Frame>

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

***

## Verify your output

<AccordionGroup>
  <Accordion title="Check commit categorization" icon="list-check">
    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](https://www.conventionalcommits.org/) format.
  </Accordion>

  <Accordion title="Validate HTML output" icon="code">
    When generating HTML output:

    ```bash theme={}
    helixcommit generate --unreleased --format html --out release.html
    ```

    Open `release.html` in a browser to verify formatting and styling.
  </Accordion>

  <Accordion title="Test with different date ranges" icon="calendar">
    Try generating notes for different ranges to ensure accuracy:

    ```bash theme={}
    # Last week's changes
    helixcommit generate --since "7 days ago" --format markdown

    # Specific commit range
    helixcommit generate --since abc123 --until def456 --format markdown
    ```
  </Accordion>
</AccordionGroup>

***

## Next steps

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

<CardGroup cols={2}>
  <Card title="CLI reference" icon="terminal" href="/cli-reference" color="#0A6ACB">
    Explore all available commands and options
  </Card>

  <Card title="Configuration" icon="gear" href="/configuration" color="#F6A02D">
    Customize HelixCommit for your workflow
  </Card>

  <Card title="AI features" icon="sparkles" href="/ai-features" color="#F26419">
    Enable AI-powered summaries for better release notes
  </Card>

  <Card title="Examples" icon="code" href="/examples" color="#0A6ACB">
    See real-world usage examples and patterns
  </Card>
</CardGroup>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="No commits found" icon="circle-exclamation">
    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`
  </Accordion>

  <Accordion title="Permission denied errors" icon="lock">
    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](https://github.com/settings/tokens)
  </Accordion>

  <Accordion title="Empty or unexpected output" icon="file-circle-question">
    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
  </Accordion>
</AccordionGroup>

<Note>
  Need more help? Check out the [full documentation](/cli-reference) or visit our [GitHub repository](https://github.com/bjornefisk/HelixCommit) to open an issue.
</Note>