Usage Guide

Practical examples and use cases for Devlog.

Basic Workflows

Release Notes Generation

Generate release notes between two versions:

# Standard release notes
devlog --from v1.0.0 --to v2.0.0 --output RELEASE_NOTES.md

# With AI summaries
devlog --from v1.0.0 --to v2.0.0 --llm ollama --output RELEASE_NOTES.md

# With detailed analysis
devlog --from v1.0.0 --to v2.0.0 \
       --llm ollama \
       --diff-analysis \
       --output RELEASE_NOTES.md

Maintaining CHANGELOG.md

Keep your changelog updated:

# Update for new release
devlog --from v1.0.0 --to HEAD \
       --llm ollama \
       --output CHANGELOG.md

# Append to existing changelog
devlog --from v1.0.0 --to HEAD --llm ollama >> CHANGELOG.md

Feature Summary for Stakeholders

Generate high-level feature overview:

devlog --from v1.0.0 --to v2.0.0 \
       --llm ollama \
       --diff-analysis \
       --group-features

Advanced Usage

Custom Ranges

# Last N commits
devlog --limit 20 --llm ollama

# Specific commit range
devlog --from abc1234 --to def5678 --llm ollama

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

Filtering and Grouping

# Group by commit type
devlog --from v1.0.0 --to v2.0.0 --group

# Include merge commits
devlog --from v1.0.0 --to v2.0.0 --include-merges

# With author attribution
devlog --from v1.0.0 --to v2.0.0 --authors

Output Formats

# Markdown (default)
devlog --from v1.0.0 --to v2.0.0 --output changelog.md

# JSON for programmatic access
devlog --from v1.0.0 --to v2.0.0 \
       --format json \
       --output changelog.json

# Pretty-print to console
devlog --from v1.0.0 --to 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 --from $PREV_TAG --to $GITHUB_REF_NAME \
                 --llm ollama \
                 --no-consent-prompt \
                 --output 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 --from $PREV_TAG --to $CI_COMMIT_TAG \
             --llm ollama \
             --no-consent-prompt \
             --output CHANGELOG.md
  artifacts:
    paths:
      - CHANGELOG.md
  only:
    - tags

Working with Different Repository Types

Monorepo

# Focus on specific path
cd packages/frontend
devlog --from v1.0.0 --to v2.0.0

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

Multiple Branches

# Compare feature branch to main
devlog --from main --to feature/new-feature

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

Privacy Modes

Local-Only (Maximum Privacy)

# Only use local LLMs
devlog --llm ollama --diff-analysis

# Never requires network access
devlog --llm llamacpp --diff-analysis

Cloud with Sanitization

# Strict mode (default) - removes all PII
devlog --llm openai --privacy-level strict

# Moderate mode - keeps file paths
devlog --llm openai --privacy-level moderate

# Check what would be sent
devlog --llm openai --dry-run

Tips & Tricks

Speed Up Analysis

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

# Limit scope
devlog --limit 50 --llm ollama

# Skip diff analysis for quick results
devlog --from v1.0.0 --to v2.0.0 --llm ollama  # no --diff-analysis

Better Results

# Use diff analysis for detailed insights
devlog --diff-analysis --llm ollama

# Group by features for overview
devlog --diff-analysis --group-features --llm ollama

# Include merge commits
devlog --include-merges --llm ollama

Debugging

# Enable debug logging
export RUST_LOG="devlog=debug"
devlog --from v1.0.0 --to v2.0.0

# Dry run to see what would be sent
devlog --llm openai --dry-run

# Estimate costs before running
devlog --llm openai --estimate-cost

Common Patterns

Pre-Release Checklist

#!/bin/bash
# Generate changelog before release
devlog --from $(git describe --tags --abbrev=0) --to HEAD \
       --llm ollama \
       --diff-analysis \
       --output 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 --from HEAD@{$LAST_WEEK} --to HEAD \
       --llm ollama \
       --diff-analysis \
       --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 --from ${lastRelease.gitTag} --to ${nextRelease.gitTag} --llm ollama --output CHANGELOG.md"
      }
    ]
  ]
}

Best Practices

See Best Practices Guide for detailed recommendations.

← Back to Home