Git Story

Turn git history into a readable narrative. Not a changelog—an actual story about what happened in your project.

"The week started with the team laser-focused on the authentication overhaul. Sarah and Mike tag-teamed the OAuth integration, with a series of rapid commits on Monday morning. By Wednesday, focus shifted to the dashboard—though an urgent production hotfix pulled everyone away briefly on Thursday night..."

Installation

npm install -g @vidhyasagarthakur/git-story

Quick Start

# Generate a story for the last 7 days
git-story generate

# Last 2 weeks with GitHub PR data
git-story generate --since 2w --github owner/repo

# Output as HTML
git-story generate --format html -o story.html

Usage

git-story generate [options]

| Option | Description | |--------|-------------| | -r, --repo <path> | Repository path (default: current directory) | | -s, --since <date> | Start date: YYYY-MM-DD, "7d", "2w" (default: 7d) | | -u, --until <date> | End date: YYYY-MM-DD, "today" (default: today) | | -p, --path <glob> | Filter by path (for monorepos) | | --provider <name> | LLM: openai, anthropic, ollama (default: openai) | | --model <name> | Model name (provider-specific) | | --style <type> | Style: narrative, summary, detailed | | --github <repo> | Include GitHub PR data (owner/repo) | | --gitlab <project> | Include GitLab MR data | | --bitbucket <repo> | Include Bitbucket PR data | | --azure <repo> | Include Azure DevOps PR data (project/repo) | | -f, --format <type> | Output: plain, markdown, slack, slack-blocks, html | | -o, --output <file> | Write to file | | --dry-run | Show collected data without generating |

LLM Providers

OpenAI (default)

export OPENAI_API_KEY=sk-...
git-story generate --provider openai --model gpt-4-turbo-preview

Anthropic (Claude)

export ANTHROPIC_API_KEY=sk-ant-...
git-story generate --provider anthropic --model claude-sonnet-4-20250514

Ollama (Local)

# Start Ollama first
git-story generate --provider ollama --model llama2

Git Platforms

GitHub

export GITHUB_TOKEN=ghp_...
git-story generate --github facebook/react

GitLab

export GITLAB_TOKEN=glpat-...
export GITLAB_URL=https://gitlab.company.com/api/v4  # Optional for self-hosted
git-story generate --gitlab mygroup/myproject

Bitbucket

export BITBUCKET_USERNAME=user
export BITBUCKET_APP_PASSWORD=...
git-story generate --bitbucket workspace/repo

Azure DevOps

export AZURE_DEVOPS_ORG=myorganization
export AZURE_DEVOPS_TOKEN=...  # PAT with Code (Read) scope
git-story generate --azure myproject/myrepo

Output Formats

Plain Text (default)

git-story generate

Markdown

git-story generate --format markdown -o STORY.md

Slack

# Simple mrkdwn format
git-story generate --format slack

# Block Kit JSON (for Slack API)
git-story generate --format slack-blocks -o slack-payload.json

HTML

git-story generate --format html -o story.html

Monorepo Support

Filter commits by path:

# Only frontend changes
git-story generate --path "packages/frontend/**"

# Only backend
git-story generate --path "src/api/**"

Examples

# Last month's work on the API
git-story generate --since 30d --path "api/**" --format markdown

# Sprint retrospective with PR data
git-story generate --since 2024-01-01 --until 2024-01-14 --github myorg/myrepo

# Quick executive summary
git-story generate --style summary --since 1w

# Detailed technical narrative
git-story generate --style detailed --format html -o sprint-review.html

What It Analyzes

• Commits: Messages, diffs, authors, timestamps
• Branches: Feature branches, merges, PR activity
• Work Patterns: Categorizes by feature/bug/refactor/docs
• Team Dynamics: Who worked on what, collaboration patterns
• Urgency Signals: Hotfixes, after-hours commits, rapid iterations
• PR Activity: Reviews, comments, time-to-merge (with platform integration)

Sample Output

The past two weeks saw significant momentum on the payments integration. The effort kicked off with Alex laying the groundwork—a series of foundational commits establishing the Stripe webhook handlers and database schema changes.

Mid-week brought an unexpected detour when a critical bug surfaced in production authentication. The team pivoted quickly, with Jordan pushing an emergency fix at 11 PM on Wednesday, followed by Maria's thorough test coverage the next morning.

By the second week, the team had returned to payments with renewed focus. The PR activity shows healthy collaboration—12 pull requests merged with an average review turnaround of just 4 hours. Notable was the refactoring effort led by Sam, consolidating three separate payment modules into a unified service layer.

The sprint closed strong with the team shipping both the new checkout flow and a surprise performance improvement that reduced API latency by 40%.

License

MIT