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

git-diff-summary analyzes, formats, and summarizes everything changed in your Git workspace. It computes line statistics, groups files by language, parses conventional commits, and can write an AI-powered overview paragraph using gpt-4o-mini before outputting formatted Markdown or JSON.

Web Studio · CLI Usage · GitHub Actions · Contributing

What it does

• 📂 Pull Request Summaries — Computes line status changes and counts (+ / -), categorizes file types, and writes Markdown tables ready for PR descriptions.
• 🚀 Conventional Changelogs — Collects commits between tags/hashes, parses conventional commit headers (feat, fix, docs, etc.), and groups them for release logs.
• 🤖 AI Summarization — Uses OpenAI gpt-4o-mini locally (with OPENAI_API_KEY) to write a concise, professional release/diff summary.
• 🖥️ Local Web Studio — Starts a local web server displaying a sleek dashboard with controls to trigger and customize outputs.

How it works (30 seconds)

 Your Local Git Repository
         │
         ├── pr: git diff --numstat + --name-status
         └── changelog: git log --format + git tag
         ▼
 ┌────────────────────────────────────────────────────────┐
 │ git-diff-summary (CLI / Studio Engine)                 │
 │ ────────────────────────────────────────────────────── │
 │  isGitRepository()  →  detectBaseBranch()               │
 │                         ├─ parseDiffStats()            │
 │                         ├─ categorizeCommits()         │
 │                         └─ summarizeChanges() (AI optional) │
 └────────────────────────────────────────────────────────┘
         │
         ▼ Markdown / JSON report output
 ┌────────────────────────────────────────────────────────┐
 │  GitHub Pull Request description / Release Changelog   │
 └────────────────────────────────────────────────────────┘

Get started

1 — Install globally

npm install -g git-diff-summary

Or execute instantly via npx:

npx git-diff-summary --help

2 — Quick commands

Run these inside any Git project:

# Generate a Pull Request description summary comparing HEAD with main/master
git-diff-summary pr

# Generate a release changelog since the latest Git tag
git-diff-summary changelog

3 — Spin up the Local Web Studio

Launch a premium local dashboard to run summaries visually:

git-diff-summary ui --port 4000

Open http://localhost:4000 in your browser.

CLI Usage

git-diff-summary pr

| Flag | Default | Description | |---|---|---| | --base <branch> | auto | Target branch (auto-detects: origin/main → origin/master → main → master). | | --ai | false | Enable AI-powered summary using gpt-4o-mini. | | --ai-key <key> | env | Provide OpenAI API Key directly. | | --format <type> | markdown | Choose markdown or json. | | --output <file>| stdout | Write output to a specific file path. |

Example:

git-diff-summary pr --base main --ai --output PR_DESCRIPTION.md

git-diff-summary changelog

| Flag | Default | Description | |---|---|---| | --from <ref> | latest tag | Tag/commit to start from (auto-detects latest tag). | | --to <ref> | HEAD | Target tag/commit. | | --ai | false | Enable AI summary for release overview. | | --ai-key <key> | env | Provide OpenAI API Key directly. | | --format <type> | markdown | Choose markdown or json. | | --output <file>| stdout | Output file target. |

Example:

git-diff-summary changelog --from v1.0.0 --to v1.1.0 --ai

git-diff-summary ui

Starts the Express server.

• -p, --port <number>: Port number (default: 4000).

Local Web Studio

The studio provides a beautiful dashboard built with a responsive glassmorphism dark theme, featuring:

• Environment API keys persistence: Enters your OpenAI API key and saves it locally in localStorage securely.
• Console output rendering: View raw text or code blocks instantly.
• Copy and Download controls: Copy the formatted markdown or download as files with one-click actions.

GitHub Actions

Create a .github/workflows/ci.yml in your project to automate checks on every push or PR:

name: CI
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0 # Essential to run git diff/log commands
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm test
      - run: npm run build

Contributing

1. Clone the repository: git clone https://github.com/salvatorecrispino7/git-diff-summary.git
2. Install dependencies: npm install
3. Execute tests: npm test
4. Build bundle: npm run build

License

MIT