Getting Started

This guide will help you install and start using Devlog in minutes.

Prerequisites

Before installing Devlog, ensure you have:

Rust 1.70 or later - Install Rust
Git - Any recent version
A Git repository - To analyze commit history
(Optional) Ollama or llama.cpp - For AI-powered features

Installation

From Source

# Clone the repository
git clone https://gitlab.com/aice/devlog.git
cd devlog

# Build release binary
cargo build --release

# The binary will be available at target/release/devlog
./target/release/devlog --help

# Optional: Install to system path
cargo install --path .

Option 3: Direct Cargo Install

# Coming soon: Install directly from crates.io
cargo install devlog

Building Without Cloud LLM Support

If you only need local LLM support:

cargo build --release --no-default-features

This removes OpenAI and Anthropic dependencies, reducing binary size.

Setting Up Local LLM (Recommended)

For privacy-first AI features, set up a local LLM:

Ollama (Easiest)

Install Ollama

# macOS/Linux
curl https://ollama.ai/install.sh | sh

# Or download from: https://ollama.ai

Pull a model

# Download llama3.2 (recommended, ~2GB)
ollama pull llama3.2

# Or use other models
ollama pull mistral
ollama pull codellama

Start Ollama server
```
ollama serve
```
The server runs on http://localhost:11434 by default.

Verify installation

devlog --llm ollama --llm-model llama3.2 --help

llama.cpp (Advanced)

Clone and build

git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp
make

Download a model
- Get GGUF format models from HuggingFace
- Place in llama.cpp/models/ directory
Start server
```
./server -m models/your-model.gguf -c 2048
```
Runs on http://localhost:8080 by default.
Verify installation
```
devlog --llm llamacpp --help
```

First Changelog

Let's generate your first changelog!

Step 1: Navigate to Your Repository

cd /path/to/your/git/repository

Step 2: Check Available Tags

git tag -l

Output example:

v1.0.0
v1.1.0
v2.0.0

Step 3: Generate Basic Changelog

# Between two versions
devlog --from v1.0.0 --to v2.0.0

# From version to current HEAD
devlog --from v2.0.0 --to HEAD

# Last 20 commits
devlog --limit 20

Output:

======================================================================
Development Log: v1.0.0 → v2.0.0
======================================================================

- [PR] feat(auth): add user authentication system (2024-01-05)
  PR: #123

- [Merge] Merge pull request #125 from feature/dashboard (2024-01-08)
  PR: #125, #126

- [Direct] refactor(auth): improve error handling (2024-01-10)

======================================================================
Summary: 3 units displayed
======================================================================

Step 4: Add AI Enhancement (Optional)

If you have Ollama installed:

devlog --from v1.0.0 --to v2.0.0 --llm ollama

Output with AI summaries:

======================================================================
Development Log: v1.0.0 → v2.0.0
======================================================================

- [PR] Add user authentication system (2024-01-05)
  PR: #123
  Summary: Implemented JWT-based authentication with secure token 
  handling and session management

- [Merge] Dashboard feature integration (2024-01-08)
  PR: #125, #126
  Summary: Integrated comprehensive dashboard with analytics, user
  preferences, and responsive design

======================================================================
Summary: 2 units displayed
======================================================================

Step 5: Try Diff Analysis

For detailed code change analysis:

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

Output with diff analysis:

======================================================================
Development Log: v1.0.0 → v2.0.0
======================================================================

- [PR] Add user authentication system (2024-01-05)
  PR: #123
  • What changed: Implemented JWT-based authentication
  • Summary:
    - Added JWT token generation and validation
    - Created login and logout endpoints
    - Added middleware for protected routes
    - Integrated bcrypt for password hashing
  • Impact: Moderate
  • Files: 8 files, +423/-12 lines

======================================================================
Summary: 1 unit displayed
======================================================================

Common Use Cases

Release Notes Generation

# Generate release notes for v2.0.0
devlog --from v1.9.0 --to v2.0.0 \
       --llm ollama \
       --diff-analysis \
       --output RELEASE_NOTES.md

Changelog File Creation

# Create/update CHANGELOG.md
devlog --from v1.0.0 --to HEAD \
       --llm ollama \
       --output CHANGELOG.md

Feature Summary for Stakeholders

# High-level feature overview
devlog --from v1.0.0 --to v2.0.0 \
       --llm ollama \
       --diff-analysis \
       --group-features

Quick Recent Changes

# Last 10 commits
devlog --limit 10 --llm ollama

CI/CD Integration

# Generate changelog in CI pipeline
devlog --from $LAST_TAG --to $CI_COMMIT_SHA \
       --llm ollama \
       --output artifacts/CHANGELOG.md \
       --no-consent-prompt

Output Options

Save to File

devlog --from v1.0.0 --to v2.0.0 --output CHANGELOG.md

JSON Output

devlog --from v1.0.0 --to v2.0.0 --format json --output changelog.json

Grouped by Commit Type

devlog --from v1.0.0 --to v2.0.0 --group

Output:

## Features
- feat(auth): add user authentication
- feat(api): implement REST endpoints

## Bug Fixes
- fix(auth): correct token expiration
- fix(db): resolve connection pool issue

With Author Information

devlog --from v1.0.0 --to v2.0.0 --authors

Output:

- feat(auth): add user authentication [abc1234] (John Doe)

Configuration

Environment Variables

Create a .env file or export in your shell:

# For cloud LLMs (optional)
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."

# Logging level
export DEVLOG_LOG_LEVEL="info"  # trace, debug, info, warn, error
export RUST_LOG="devlog=debug"

# Privacy mode (for cloud providers)
export DEVLOG_PRIVACY_MODE="strict"  # strict, moderate, relaxed

Privacy Levels

When using cloud providers:

# Maximum privacy (default)
devlog --llm openai --privacy-level strict

# Keep file paths
devlog --llm openai --privacy-level moderate

# No sanitization (local LLMs only)
devlog --llm ollama --privacy-level relaxed

Verifying Installation

Check Version

devlog --version

Run Tests

cd devlog
cargo test

Check Help

devlog --help

Test with Sample Repository

# Clone a sample repository
git clone https://github.com/rust-lang/rust-analyzer.git
cd rust-analyzer

# Generate changelog
devlog --limit 10

Troubleshooting

"Command not found: devlog"

Solution 1: Use full path

./target/release/devlog --help

Solution 2: Install to system

cargo install --path .
# Ensure ~/.cargo/bin is in PATH

"Failed to connect to Ollama"

Check Ollama is running:

curl http://localhost:11434/api/tags

Start Ollama:

ollama serve

"No commits found in range"

Check your Git tags:

git tag -l
git log --oneline

Use valid references:

# Use commit hashes instead
devlog --from abc1234 --to def5678

"API key not found"

For OpenAI:

export OPENAI_API_KEY="sk-..."

For Anthropic:

export ANTHROPIC_API_KEY="sk-ant-..."

"Permission denied"

Make binary executable:

chmod +x target/release/devlog

Next Steps

Now that you have Devlog installed:

Explore Features - Learn about all available features
Read Usage Guide - Detailed usage examples
Best Practices - Tips for optimal results
Troubleshooting - Solutions to common issues

Getting Help

Documentation: GitLab Pages
Issues: GitLab
Discussions: GitLab Discussions

← Back to Home | Next: Features →

Devlog Documentation