██████╗ ██████╗      ██████╗  ███████╗███████╗ ██████╗
██╔══██╗██╔══██╗     ██╔═══██╗██╔════╝██╔════╝ ██╔═══╝
██████╔╝██████╔╝     ██║   ██║█████╗  ███████╗ ██║
██╔═══╝ ██╔══██╗     ██║   ██║██╔══╝      ╚██║ ██║
██║     ██║  ██║     ╚██████╔╝███████╗███████║ ██████╗
╚═╝     ╚═╝  ╚═╝      ╚═════╝ ╚══════╝╚══════╝ ╚═════╝

PR DESC

An intelligent command-line interface (CLI) tool designed to streamline your development workflow by automatically generating comprehensive Pull Request (PR) descriptions and Conventional Commit messages from your Git changes. Leveraging free and open-source AI models, pr-desc analyzes your commits and file modifications to craft clear, concise, and structured PR summaries, saving you time and ensuring consistent documentation. The CLI also supports direct creation and updating of GitHub Pull Requests, as well as automatic generation of Conventional Commit messages, making your workflow faster and more consistent.

Features

• 🤖 AI-Powered Generation: Utilizes advanced AI models to analyze Git diffs, commit messages, and file changes for intelligent description generation.
• 📝 Flexible Output Templates: Choose from predefined standard, detailed, or minimal PR description formats to match your team's conventions.
• ⚡ Fast & Free: Integrates with high-performance, free-tier AI providers like Groq or local models via Ollama, ensuring rapid generation without cost barriers.
• 🔑 Seamless Configuration: Store API keys and default settings globally, allowing pr-desc to be used effortlessly from any project directory.
• 📋 Model Transparency: Easily list and select from a range of supported AI models for each provider.
• ✨ Custom Template Files: Provide your own Markdown file as a template for highly tailored PR descriptions.
• 🚀 Direct PR Creation: Automatically create or update GitHub Pull Requests directly from the CLI populated with AI-generated descriptions.
• ✍️ AI Commit Messages: Generate Conventional Commit messages automatically during PR creation or via a standalone command.
• 👀 Preview & Regenerate: When generating PR descriptions, preview the content first, then decide whether to regenerate, proceed, or cancel.
• 🧪 Dry Run Mode for Generation: Preview AI-generated PR descriptions without actually creating a PR or consuming API quotas.
• 🔧 Robust & Reliable: Built with TypeScript for enhanced type safety and maintainability.

Installation

To get started with pr-desc, install it globally via npm:

npm install -g pr-desc-cli

Setup (Recommended)

Before using pr-desc to generate descriptions, you need to configure your AI provider's API key if you're not using a local model like Llama3.1. You have several convenient options:

Setup with Interactive Wizard (Recommended)

For a quick and guided setup, run the interactive wizard:

pr-desc init

This will prompt you for your preferred AI provider, API keys, default template, and base branch, saving your choices to a global configuration file.

Manual Setup

Option 1: Use Providers Like Groq

This method stores your API key securely in a global configuration file (~/.pr-desc/config.json), making it accessible from any directory.

For Groq (recommended for speed):

pr-desc config set groq your_groq_api_key_here

You can verify your stored configuration at any time (API keys are masked by default):

pr-desc config show  # masked api keys

# Unmask (shows real key values)
pr-desc config show --unmask
pr-desc config show -u

API keys are now displayed in masked form unless you explicitly pass --unmask / -u.

Option 2: Use Local Models with Ollama

For a good balance of performance and resource usage, I recommend using llama3.1:70b. It's powerful yet efficient for generating PR descriptions.

Setup Steps:

1. Install Ollama:

   • Download the macOS application from https://ollama.ai/download.

2. Pull the llama3.1:70b Model: Open your Terminal and run:

   ollama pull llama3.1:70b

3. Set your provider config to local

   pr-desc config set local ollama

4. Use pr-desc with the Local Model: Once llama3.1:70b is pulled, specify the local provider and model:

   pr-desc generate --provider local --model llama3.1:70b

Usage

Try pr-desc in any of your local Git repositories with unmerged changes to generate a PR description.

Generate PR Description

pr-desc generate

pr-desc gen -b develop # Use a different base branch for comparison

pr-desc gen --template detailed # Apply a predefined PR template style

pr-desc gen --template-file ./my-pr-template.md # Use a custom template file

pr-desc gen --max-files 15 # Limit the number of files analyzed (default is 20)

pr-desc generate --dry-run # Returns a decorated preview output

pr-desc gen --gh-pr # Create or update existing GitHub PR using gh CLI

Seamless Integration with GitHub CLI (gh)

You can seamlessly integrate pr-desc with the GitHub CLI to automatically create or edit pull requests with the AI-generated description.

Prerequisites:

1. Install GitHub CLI (gh): Follow the installation instructions on the official GitHub CLI documentation.
2. Authenticate gh: Run gh auth login and follow the prompts to authenticate with your GitHub account.

How to use:

pr-desc gen --gh-pr

During this interactive flow, if uncommitted changes are found you can:

• Auto-generate an AI Conventional Commit message
• Manually enter a message
• Stash or cancel

In addition to auto-generate commit message here on generate now there's separate commit command you can see commit section for more

🆒 Cool additions:

• If issues occur (like uncommitted changes or a branch not pushed to origin), pr-desc will guide you through them.
• If you choose to commit during the flow, you may select AI commit generation to produce a Conventional Commit message automatically.

List Available Models

Discover which AI models are supported by each provider:

pr-desc models # List all available providers and their default models
pr-desc models --help

Manage Configuration

Control your pr-desc settings and API keys:

pr-desc config show # Display your entire global configuration
pr-desc config --help # Show all options

# unmask api keys when showing config
pr-desc config show --unmask
pr-desc config show -u

Generate AI Conventional Commit Message (Standalone)

You can now generate conventional Commit message just like generating a PR description with the commit command.

pr-desc commit # stages changes unless specified with --no-stage
pr-desc commit --type-hint feat # provide your own type hint
pr-desc commit --no-stage # show suggested commit (don’t auto-commit) same as --dry-run
pr-desc commit --commit

# Some generic options of pr-desc generate are also available here eg. Providers, models and base branch
pr-desc commit -p groq -m claude-3.5-sonnet
pr-desc commit -b develop

Available Templates

pr-desc offers three built-in templates to structure your PR descriptions:

• standard - (Default) A balanced description including a clear title, a summary of changes, rationale, and notes.
• detailed - A comprehensive description with dedicated sections for Summary, Changes Made, Technical Details, Testing instructions, Breaking Changes, and Additional Notes.
• minimal - A concise one-line summary followed by brief bullet points.

pr-desc gen --template <template>

Use Custom Template

You can provide your own Markdown file as a template for generating PR descriptions using the --template-file <path> option.

Example my-pr-template.md:

# Title

[Short, clear title summarizing the change in under 10 words.]

## Summary of Changes

[Concise, high-level overview of what this pull request does.]

## What Was Changed

[List specific modifications, features added, bugs fixed, or files updated.]

## Why This Change Was Made

[Explain the reason for the change. Include the problem it solves.]

## Technical Details

[Include implementation details, dependencies, DB changes, env vars, APIs.]

## Breaking Changes

[List any breaking changes or write `None`. Include migration instructions.]

The AI will analyze the git changes and fill in the sections of your custom template.

Supported Providers & Available Models

The CLI supports the following providers and models. Use -m / --model to specify:

| Provider | Default Model | Other Options | | -------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | Groq | claude-3.5-sonnet | llama-3.1-70b-versatile, llama-3.3-70b-versatile, mixtral-8x22b-instruct, gemma2-27b-it, deepseek-v3 | | Local | llama3.1:70b | codegemma:2b, phi3:3.8b-mini-4k-instruct, qwen2-coder:32b, mixtral:8x22b, gemma2:27b, deepseek-coder:33b, llama3.3:70b, codellama:70b |