Usage Guide

Practical examples and use cases for Devlog.

Basic Workflows

Release Notes Generation

Generate release notes between two versions:

# Plain mode — -o flag writes to file, --format controls format
devlog -f v1.0.0 -t v2.0.0 -o RELEASE_NOTES.md

# With AI diff analysis — output always goes to stdout, redirect to file
devlog -f v1.0.0 -t v2.0.0 --llm ollama:llama3.2 > RELEASE_NOTES.md

# With AI but without diff analysis — -o flag works here
devlog -f v1.0.0 -t v2.0.0 \
       --llm ollama:llama3.2 \
       --no-diff \
       -o RELEASE_NOTES.md

Maintaining CHANGELOG.md

Keep your changelog updated:

# Update for new release (LLM mode outputs to stdout — redirect to file)
devlog -f v1.0.0 -t HEAD \
       --llm ollama:llama3.2 \
       > CHANGELOG.md

# Append to existing changelog
devlog -f v1.0.0 -t HEAD --llm ollama:llama3.2 >> CHANGELOG.md

Feature Summary for Stakeholders

Generate high-level feature overview:

devlog -f v1.0.0 -t v2.0.0 \
       --llm ollama:llama3.2 \
       --group-features

Advanced Usage

Custom Ranges

# Last N commits
devlog -n 20 --llm ollama:llama3.2

# Specific commit range
devlog -f abc1234 -t def5678 --llm ollama:llama3.2

# Since yesterday (using git syntax)
devlog -f HEAD@{1.day.ago} -t HEAD

Filtering and Grouping

# Group by commit type
devlog -f v1.0.0 -t v2.0.0 --group-by-type

# Include merge commits
devlog -f v1.0.0 -t v2.0.0 --include-merges

# With author attribution
devlog -f v1.0.0 -t v2.0.0 --authors

Output Formats

# Markdown (default)
devlog -f v1.0.0 -t v2.0.0 -o changelog.md

# JSON for programmatic access
devlog -f v1.0.0 -t v2.0.0 \
       --format json \
       -o changelog.json

# Pretty-print to console
devlog -f v1.0.0 -t v2.0.0

CI/CD Integration

GitHub Actions

name: Generate Changelog

on:
  push:
    tags:
      - 'v*'

jobs:
  changelog:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Install Devlog
        run: |
          cargo install --git https://gitlab.com/aice/devlog.git

      - name: Setup Ollama
        run: |
          curl https://ollama.ai/install.sh | sh
          ollama pull llama3.2

      - name: Generate Changelog
        run: |
          PREV_TAG=$(git describe --tags --abbrev=0 HEAD^)
          devlog -f $PREV_TAG -t $GITHUB_REF_NAME \
                 --llm ollama:llama3.2 \
                 -y \
                 > CHANGELOG.md

      - name: Upload Changelog
        uses: actions/upload-artifact@v4
        with:
          name: changelog
          path: CHANGELOG.md

GitLab CI

generate_changelog:
  stage: deploy
  image: rust:latest
  script:
    - cargo install --git https://gitlab.com/aice/devlog.git
    - curl https://ollama.ai/install.sh | sh
    - ollama serve &
    - ollama pull llama3.2
    - PREV_TAG=$(git describe --tags --abbrev=0 HEAD^)
    - devlog -f $PREV_TAG -t $CI_COMMIT_TAG \
             --llm ollama:llama3.2 \
             -y \
             > CHANGELOG.md
  artifacts:
    paths:
      - CHANGELOG.md
  only:
    - tags

Working with Different Repository Types

Monorepo

# Focus on specific path
cd packages/frontend
devlog -f v1.0.0 -t v2.0.0

# Or filter by scope
devlog -f v1.0.0 -t v2.0.0 | grep "feat(frontend)"

Multiple Branches

# Compare feature branch to main
devlog -f main -t feature/new-feature

# Changes in current branch since branching
devlog -f $(git merge-base main HEAD) -t HEAD

Privacy Modes

Local-Only (Maximum Privacy)

# Only use local LLMs (diff analysis is automatic with --llm)
devlog --llm ollama:llama3.2

# Never requires network access
devlog --llm llamacpp:model-name

Cloud with Sanitization

# Strict mode (default) - removes all PII
devlog --llm openai:gpt-4-turbo --privacy strict

# Moderate mode - keeps file paths
devlog --llm openai:gpt-4-turbo --privacy moderate

# Check what would be sent
devlog --llm openai:gpt-4-turbo --dry-run

Tips & Tricks

Speed Up Analysis

# Use smaller model
devlog --llm ollama:llama3.2  # instead of larger models

# Limit scope
devlog -n 50 --llm ollama:llama3.2

# Skip diff analysis for quick results
devlog -f v1.0.0 -t v2.0.0 --llm ollama:llama3.2 --no-diff

Better Results

# Diff analysis is automatic with --llm
devlog --llm ollama:llama3.2

# Group by features for overview
devlog --group-features --llm ollama:llama3.2

# Include merge commits
devlog --include-merges --llm ollama:llama3.2

Debugging

# Enable debug logging
export RUST_LOG="devlog=debug"
devlog -f v1.0.0 -t v2.0.0

# Dry run to see what would be sent
devlog --llm openai:gpt-4-turbo --dry-run

# Estimate costs before running
devlog --llm openai:gpt-4-turbo --estimate-cost

Common Patterns

Pre-Release Checklist

#!/bin/bash
# Generate changelog before release (LLM mode — redirect stdout to file)
devlog -f $(git describe --tags --abbrev=0) -t HEAD \
       --llm ollama:llama3.2 \
       > RELEASE_NOTES.md

# Review generated changelog
cat RELEASE_NOTES.md

# Create release commit
git add RELEASE_NOTES.md
git commit -m "docs: update release notes for vX.Y.Z"

Weekly Team Updates

#!/bin/bash
# Generate weekly summary
LAST_WEEK=$(date -d "7 days ago" +%Y-%m-%d)
devlog -f HEAD@{$LAST_WEEK} -t HEAD \
       --llm ollama:llama3.2 \
       --group-features

Integration with Semantic Release

# In .releaserc.js or package.json
{
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    [
      "@semantic-release/exec",
      {
        "prepareCmd": "devlog -f ${lastRelease.gitTag} -t ${nextRelease.gitTag} --llm ollama:llama3.2 > CHANGELOG.md"
      }
    ]
  ]
}

Best Practices

See Best Practices Guide for detailed recommendations.

← Back to Home

Devlog Documentation