git-history-extraction 0.1.0__tar.gz

git_history_extraction-0.1.0/PKG-INFO

@@ -0,0 +1,259 @@
+Metadata-Version: 2.3
+Name: git-history-extraction
+Version: 0.1.0
+Summary: Extract and analyze git commit history with support for filtering by trailers, date ranges, and AI-powered summarization for changelogs
+Keywords: git,changelog,history,commit,trailers,ai,summarization,openai,gemini
+Author: Michael Bianco
+Author-email: Michael Bianco <mike@mikebian.co>
+Requires-Dist: click>=8.0
+Requires-Python: >=3.10
+Project-URL: Repository, https://github.com/iloveitaly/git-history-extraction
+Description-Content-Type: text/markdown
+
+# git-history-extraction
+
+A tool to extract and filter git commit history, making it easy to pipe to AI tools for changelog generation and summaries.
+
+## Features
+
+- Extract git commits with metadata (SHA, date, files, message)
+- Filter commits by time range or starting commit
+- Extract and filter git trailers (e.g., `Co-authored-by`, `User-Facing`)
+- Output in simple text or JSON format
+- Pipe output to AI tools (OpenAI, Gemini, Claude) for automated summarization
+
+## Installation
+
+### Using uv (Recommended)
+
+No installation needed! The tool can be run directly:
+
+```bash
+uv run git-history-extraction --help
+```
+
+### Install as Package
+
+```bash
+pip install git-history-extraction
+```
+
+## Usage
+
+### Basic Examples
+
+Extract commits from the last 24 hours (default):
+```bash
+git-history-extraction
+```
+
+Extract commits from the last 7 days:
+```bash
+git-history-extraction --since "7 days ago"
+```
+
+Extract commits from a specific repository:
+```bash
+git-history-extraction --repo /path/to/repo --since "1 week ago"
+```
+
+### Output Formats
+
+Simple text format (default):
+```bash
+git-history-extraction --since "1 day ago"
+```
+
+JSON format for piping to other tools:
+```bash
+git-history-extraction --since "1 day ago" --format json
+```
+
+### Commit Range Selection
+
+By time range:
+```bash
+git-history-extraction --since "2024-01-01"
+```
+
+From a specific commit to HEAD:
+```bash
+git-history-extraction --since-commit abc1234
+```
+
+### Git Trailers
+
+Extract specific trailers only (case-insensitive):
+```bash
+git-history-extraction --since "1 week ago" --trailers "co-authored-by,reviewed-by"
+```
+
+## Piping to AI Tools for Summarization
+
+This tool extracts and formats git history, making it easy to pipe to AI tools for summarization. The tool itself **does not perform AI summarization**—it prepares the data so you can use your preferred AI tool.
+
+The tool enables you to extract targeted slices of git history for different audiences. For example, use git trailers like `User-Facing:` to mark end-user changes, then extract and pipe them to AI for changelogs or internal notifications.
+
+### Creating Structured Git Trailers with AI
+
+Combine with [aiautocommit](https://github.com/iloveitaly/aiautocommit) to automatically generate git trailers during commits. This creates a structured history that can be easily filtered and summarized for different audiences.
+
+**Example custom commit prompt for aiautocommit:**
+
+```markdown
+# IMPORTANT: Your Instructions
+
+You are an expert software developer. Generate a commit message from the `git diff` output below using these rules:
+
+## 1. Subject Line
+
+- Use a conventional commit prefix:
+  - `feat`: New features
+  - `fix`: Bug fixes, including user-visible design or style fixes.
+  - `docs`: Changes only to internal documentation (e.g., `.md`, `.rst`) or code comments.
+  - `style`: Formatting, linting, or code style changes in code files.
+  - `refactor`: Code structure improvements (no behavior changes).
+  - `build`: Updates to build scripts or configs (e.g., `Makefile`, `Justfile`, `Dockerfile`, `package.json`).
+  - `deploy`: Deployment script or IAC updates.
+  - `test`: Changes to tests
+- Add optional scope in parentheses when changes affect a specific module (e.g., `feat(auth): add login`)
+- Limit to 50 characters after the prefix and scope.
+- Use imperative mood (e.g., "improve layout").
+- Describe the intent or outcome (e.g., "prevent text overflow" not "add break-all").
+- Be specific about the change ("validate email format" not "improve validation").
+
+## 2. Extended Commit Message
+
+- Include only if changes have non-obvious implications, fix complex bugs, or introduce breaking changes.
+- Separate from subject with one blank line.
+- Use markdown bullets focusing on **why** the change was needed and **what impact** it has.
+- Mention side effects, user impact, or important trade-offs.
+
+## 3. User-facing Changes
+
+If the change is something that a end-user (not internal admin!) would see, include a `User-facing:` git trailer with a sentence
+or two explaining, to the user, what they would see differently because of this change.
+
+## 4. General Guidelines
+
+- Prioritize the purpose of changes over listing tools or properties used.
+- Keep concise; avoid obvious or verbose details.
+- Always generate a message based on the diff, even with limited context.
+
+## 5. Scopes
+
+Optional scopes (e.g., `feat(api):`):
+
+- `match`: frontend or backend changes tied
+- `site`: content, additional pages, etc for the static site content
+- `internal-admin`: internal admin changes (including CMS)
+```
+
+With this setup, commits automatically get `User-facing:` trailers. You can then extract and summarize them:
+
+```bash
+# Extract only user-facing changes from the last sprint
+git-history-extraction --since "last monday" --trailers "User-facing" | \
+  gemini -i "Create a user-friendly changelog from these changes"
+```
+
+### Using with Gemini CLI
+
+Extract user-facing changes and generate a non-technical summary:
+```bash
+git-history-extraction --repo . --since "last monday" \
+  --trailers "User-Facing" | \
+  gemini -i "This is a compressed git history identifying user-facing changes. \
+Can you write a 1-2 sentence overview of the changes, with a list of bullets \
+identifying changes. This is for a non-technical internal audience, letting \
+them know what the development team has done. Separate into 'new' and 'fixed' \
+sections. Include a 'Updates Since' with the date of the first commit in the \
+history. Remove fluff, keep it concise and information dense."
+```
+
+### Using the OpenAI Playground Script (Optional)
+
+An optional playground script is included that demonstrates OpenAI integration:
+
+```bash
+# Generate summary with OpenAI
+git-history-extraction --since "1 week ago" --format json | \
+  uv run playground/summarize_commits.py
+
+# Preview the prompt without calling OpenAI
+git-history-extraction --since "1 week ago" --format json | \
+  uv run playground/summarize_commits.py --dump-prompt
+```
+
+**Requirements:**
+- `OPENAI_API_KEY` environment variable
+- The script uses GPT-4o-mini by default
+
+This is just an example—you can pipe to any AI tool you prefer. See [playground/README.md](playground/README.md) for more details.
+
+## Output Format
+
+### Simple Format
+
+Each commit is displayed with:
+- **Commit:** SHA hash
+- **Date:** ISO 8601 timestamp
+- **Files:** Comma-separated list of changed files
+- **Message:** Commit body with trailers removed
+
+### JSON Format
+
+Array of commit objects:
+```json
+[
+  {
+    "sha": "abc123...",
+    "date": "2024-10-31T08:00:00-06:00",
+    "body": "commit message with trailers",
+    "files": ["file1.py", "file2.md"]
+  }
+]
+```
+
+## Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--since TEXT` | ISO date/time or relative time | `"24 hours ago"` |
+| `--since-commit TEXT` | Start from specific commit (overrides `--since`) | None |
+| `--repo DIRECTORY` | Path to git repository | `.` (current directory) |
+| `--trailers TEXT` | Comma-separated trailer keys to extract | None (show all) |
+| `--format [simple\|json]` | Output format | `simple` |
+
+## How It Works
+
+- Uses `git log` with custom formatting for efficient single-pass extraction
+- Parses commit metadata, body, and file changes in one command
+- Intelligently extracts git trailers from commit messages
+- No per-commit subprocess calls for optimal performance
+
+## Development
+
+The main logic lives in `git_history_extraction/__init__.py`. The tool is structured as a Python package with:
+
+- **main.py:** Entry point script
+- **git_history_extraction/:** Core module with extraction logic
+- **playground/:** Optional AI summarization scripts
+
+### Running Tests
+
+```bash
+pytest
+```
+
+## Limitations
+
+- Large commit ranges may generate significant output; consider narrowing the time range
+- This tool extracts and formats data only—AI summarization requires external tools
+- Git must be available in PATH
+
+## Requirements
+
+- Python >= 3.9
+- git
+- [uv](https://docs.astral.sh/uv/) (recommended) or pip

git_history_extraction-0.1.0/README.md

@@ -0,0 +1,247 @@
+# git-history-extraction
+
+A tool to extract and filter git commit history, making it easy to pipe to AI tools for changelog generation and summaries.
+
+## Features
+
+- Extract git commits with metadata (SHA, date, files, message)
+- Filter commits by time range or starting commit
+- Extract and filter git trailers (e.g., `Co-authored-by`, `User-Facing`)
+- Output in simple text or JSON format
+- Pipe output to AI tools (OpenAI, Gemini, Claude) for automated summarization
+
+## Installation
+
+### Using uv (Recommended)
+
+No installation needed! The tool can be run directly:
+
+```bash
+uv run git-history-extraction --help
+```
+
+### Install as Package
+
+```bash
+pip install git-history-extraction
+```
+
+## Usage
+
+### Basic Examples
+
+Extract commits from the last 24 hours (default):
+```bash
+git-history-extraction
+```
+
+Extract commits from the last 7 days:
+```bash
+git-history-extraction --since "7 days ago"
+```
+
+Extract commits from a specific repository:
+```bash
+git-history-extraction --repo /path/to/repo --since "1 week ago"
+```
+
+### Output Formats
+
+Simple text format (default):
+```bash
+git-history-extraction --since "1 day ago"
+```
+
+JSON format for piping to other tools:
+```bash
+git-history-extraction --since "1 day ago" --format json
+```
+
+### Commit Range Selection
+
+By time range:
+```bash
+git-history-extraction --since "2024-01-01"
+```
+
+From a specific commit to HEAD:
+```bash
+git-history-extraction --since-commit abc1234
+```
+
+### Git Trailers
+
+Extract specific trailers only (case-insensitive):
+```bash
+git-history-extraction --since "1 week ago" --trailers "co-authored-by,reviewed-by"
+```
+
+## Piping to AI Tools for Summarization
+
+This tool extracts and formats git history, making it easy to pipe to AI tools for summarization. The tool itself **does not perform AI summarization**—it prepares the data so you can use your preferred AI tool.
+
+The tool enables you to extract targeted slices of git history for different audiences. For example, use git trailers like `User-Facing:` to mark end-user changes, then extract and pipe them to AI for changelogs or internal notifications.
+
+### Creating Structured Git Trailers with AI
+
+Combine with [aiautocommit](https://github.com/iloveitaly/aiautocommit) to automatically generate git trailers during commits. This creates a structured history that can be easily filtered and summarized for different audiences.
+
+**Example custom commit prompt for aiautocommit:**
+
+```markdown
+# IMPORTANT: Your Instructions
+
+You are an expert software developer. Generate a commit message from the `git diff` output below using these rules:
+
+## 1. Subject Line
+
+- Use a conventional commit prefix:
+  - `feat`: New features
+  - `fix`: Bug fixes, including user-visible design or style fixes.
+  - `docs`: Changes only to internal documentation (e.g., `.md`, `.rst`) or code comments.
+  - `style`: Formatting, linting, or code style changes in code files.
+  - `refactor`: Code structure improvements (no behavior changes).
+  - `build`: Updates to build scripts or configs (e.g., `Makefile`, `Justfile`, `Dockerfile`, `package.json`).
+  - `deploy`: Deployment script or IAC updates.
+  - `test`: Changes to tests
+- Add optional scope in parentheses when changes affect a specific module (e.g., `feat(auth): add login`)
+- Limit to 50 characters after the prefix and scope.
+- Use imperative mood (e.g., "improve layout").
+- Describe the intent or outcome (e.g., "prevent text overflow" not "add break-all").
+- Be specific about the change ("validate email format" not "improve validation").
+
+## 2. Extended Commit Message
+
+- Include only if changes have non-obvious implications, fix complex bugs, or introduce breaking changes.
+- Separate from subject with one blank line.
+- Use markdown bullets focusing on **why** the change was needed and **what impact** it has.
+- Mention side effects, user impact, or important trade-offs.
+
+## 3. User-facing Changes
+
+If the change is something that a end-user (not internal admin!) would see, include a `User-facing:` git trailer with a sentence
+or two explaining, to the user, what they would see differently because of this change.
+
+## 4. General Guidelines
+
+- Prioritize the purpose of changes over listing tools or properties used.
+- Keep concise; avoid obvious or verbose details.
+- Always generate a message based on the diff, even with limited context.
+
+## 5. Scopes
+
+Optional scopes (e.g., `feat(api):`):
+
+- `match`: frontend or backend changes tied
+- `site`: content, additional pages, etc for the static site content
+- `internal-admin`: internal admin changes (including CMS)
+```
+
+With this setup, commits automatically get `User-facing:` trailers. You can then extract and summarize them:
+
+```bash
+# Extract only user-facing changes from the last sprint
+git-history-extraction --since "last monday" --trailers "User-facing" | \
+  gemini -i "Create a user-friendly changelog from these changes"
+```
+
+### Using with Gemini CLI
+
+Extract user-facing changes and generate a non-technical summary:
+```bash
+git-history-extraction --repo . --since "last monday" \
+  --trailers "User-Facing" | \
+  gemini -i "This is a compressed git history identifying user-facing changes. \
+Can you write a 1-2 sentence overview of the changes, with a list of bullets \
+identifying changes. This is for a non-technical internal audience, letting \
+them know what the development team has done. Separate into 'new' and 'fixed' \
+sections. Include a 'Updates Since' with the date of the first commit in the \
+history. Remove fluff, keep it concise and information dense."
+```
+
+### Using the OpenAI Playground Script (Optional)
+
+An optional playground script is included that demonstrates OpenAI integration:
+
+```bash
+# Generate summary with OpenAI
+git-history-extraction --since "1 week ago" --format json | \
+  uv run playground/summarize_commits.py
+
+# Preview the prompt without calling OpenAI
+git-history-extraction --since "1 week ago" --format json | \
+  uv run playground/summarize_commits.py --dump-prompt
+```
+
+**Requirements:**
+- `OPENAI_API_KEY` environment variable
+- The script uses GPT-4o-mini by default
+
+This is just an example—you can pipe to any AI tool you prefer. See [playground/README.md](playground/README.md) for more details.
+
+## Output Format
+
+### Simple Format
+
+Each commit is displayed with:
+- **Commit:** SHA hash
+- **Date:** ISO 8601 timestamp
+- **Files:** Comma-separated list of changed files
+- **Message:** Commit body with trailers removed
+
+### JSON Format
+
+Array of commit objects:
+```json
+[
+  {
+    "sha": "abc123...",
+    "date": "2024-10-31T08:00:00-06:00",
+    "body": "commit message with trailers",
+    "files": ["file1.py", "file2.md"]
+  }
+]
+```
+
+## Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--since TEXT` | ISO date/time or relative time | `"24 hours ago"` |
+| `--since-commit TEXT` | Start from specific commit (overrides `--since`) | None |
+| `--repo DIRECTORY` | Path to git repository | `.` (current directory) |
+| `--trailers TEXT` | Comma-separated trailer keys to extract | None (show all) |
+| `--format [simple\|json]` | Output format | `simple` |
+
+## How It Works
+
+- Uses `git log` with custom formatting for efficient single-pass extraction
+- Parses commit metadata, body, and file changes in one command
+- Intelligently extracts git trailers from commit messages
+- No per-commit subprocess calls for optimal performance
+
+## Development
+
+The main logic lives in `git_history_extraction/__init__.py`. The tool is structured as a Python package with:
+
+- **main.py:** Entry point script
+- **git_history_extraction/:** Core module with extraction logic
+- **playground/:** Optional AI summarization scripts
+
+### Running Tests
+
+```bash
+pytest
+```
+
+## Limitations
+
+- Large commit ranges may generate significant output; consider narrowing the time range
+- This tool extracts and formats data only—AI summarization requires external tools
+- Git must be available in PATH
+
+## Requirements
+
+- Python >= 3.9
+- git
+- [uv](https://docs.astral.sh/uv/) (recommended) or pip

git_history_extraction-0.1.0/git_history_extraction/__init__.py

@@ -0,0 +1,189 @@
+import subprocess
+import re
+from pathlib import Path
+import click
+
+
+def get_commit_files(sha: str, repo_path: Path | None = None) -> list[str]:
+    cmd = ["git", "diff-tree", "--no-commit-id", "--name-only", "-r", sha]
+    result = subprocess.run(
+        cmd,
+        capture_output=True,
+        text=True,
+        check=True,
+        cwd=str(repo_path) if repo_path else None,
+    )
+    return [l.strip() for l in result.stdout.splitlines() if l.strip()]
+
+
+def get_git_commits(since, since_commit=None, repo_path: Path | None = None):
+    rec_sep = "\x1e"
+    fld_sep = "\x1f"
+    end_hdr = "\x1d"
+
+    pretty = f"{rec_sep}%H{fld_sep}%cI{fld_sep}%B{end_hdr}"
+    if since_commit:
+        cmd = [
+            "git",
+            "log",
+            f"{since_commit}..HEAD",
+            f"--pretty=format:{pretty}",
+            "--name-only",
+        ]
+    else:
+        cmd = [
+            "git",
+            "log",
+            f"--since={since}",
+            f"--pretty=format:{pretty}",
+            "--name-only",
+        ]
+
+    result = subprocess.run(
+        cmd,
+        capture_output=True,
+        text=True,
+        check=True,
+        cwd=str(repo_path) if repo_path else None,
+    )
+
+    commits: list[dict] = []
+    stream = result.stdout
+    for block in stream.split(rec_sep):
+        if not block.strip():
+            continue
+        if end_hdr not in block:
+            continue
+        header, files_blob = block.split(end_hdr, 1)
+        parts = header.split(fld_sep, 2)
+        if len(parts) != 3:
+            continue
+        sha, date_iso, body = parts
+        files = [l.strip() for l in files_blob.splitlines() if l.strip()]
+        commits.append(
+            {
+                "sha": sha.strip(),
+                "date": date_iso.strip(),
+                "body": body.strip(),
+                "files": files,
+            }
+        )
+
+    return commits
+
+
+def remove_git_trailers(commit_body: str) -> str:
+    lines = commit_body.splitlines()
+    trailer_regex = re.compile(r"^\s*[-*]?\s*[^:]+:\s*.*$")
+
+    while lines and not lines[-1].strip():
+        lines.pop()
+
+    while lines and trailer_regex.match(lines[-1]):
+        lines.pop()
+
+    while lines and not lines[-1].strip():
+        lines.pop()
+
+    return "\n".join(lines)
+
+
+def extract_git_trailers(commit_body: str) -> list[tuple[str, str]]:
+    lines = commit_body.splitlines()
+    trailer_regex = re.compile(r"^\s*[-*]?\s*([^:]+):\s*(.*)$")
+
+    idx = len(lines) - 1
+    while idx >= 0 and not lines[idx].strip():
+        idx -= 1
+
+    collected: list[tuple[str, str]] = []
+    seen_keys: set[tuple[str, str]] = set()
+    j = idx
+    while j >= 0:
+        m = trailer_regex.match(lines[j])
+        if not m:
+            break
+        pair = (m.group(1), m.group(2))
+        collected.append(pair)
+        seen_keys.add((m.group(1).strip().lower(), m.group(2).strip()))
+        j -= 1
+    collected.reverse()
+
+    for line in lines:
+        m = trailer_regex.match(line)
+        if not m:
+            continue
+        key_norm = (m.group(1).strip().lower(), m.group(2).strip())
+        if key_norm in seen_keys:
+            continue
+        collected.append((m.group(1), m.group(2)))
+        seen_keys.add(key_norm)
+
+    return collected
+
+
+@click.command()
+@click.option(
+    "--since",
+    type=str,
+    default="24 hours ago",
+    help="ISO date/time or relative time (default: '24 hours ago')",
+)
+@click.option(
+    "--since-commit",
+    type=str,
+    default=None,
+    help="Specific commit sha to start from (e.g. abc123). Overrides --since if provided.",
+)
+@click.option(
+    "--repo",
+    type=click.Path(exists=True, file_okay=False, dir_okay=True, path_type=Path),
+    default=Path("."),
+    help="Path to the git repository to summarize.",
+)
+@click.option(
+    "--trailers",
+    type=str,
+    default=None,
+    help="Comma-separated trailer key(s) to output (case-insensitive).",
+)
+@click.option(
+    "--format",
+    type=click.Choice(["simple", "json"]),
+    default="simple",
+    help="Output format (default: simple)",
+)
+def main(since: str, since_commit: str | None, repo: Path, trailers: str | None, format: str):
+    commits = get_git_commits(since, since_commit, repo_path=repo)
+    if not commits:
+        click.echo("No commits found using the specified parameters.")
+        return
+
+    if trailers is not None:
+        selectors = {part.strip().lower() for part in trailers.split(",") if part.strip()}
+        out_lines: list[str] = []
+        for c in commits:
+            trailer_items = extract_git_trailers(c["body"]) or []
+            if selectors:
+                trailer_items = [t for t in trailer_items if t[0].lower() in selectors]
+            if not trailer_items:
+                continue
+            files = ", ".join(c.get("files", []))
+            out_lines.append(f"Commit: {c['sha']}\nDate: {c['date']}\nFiles: {files}")
+            out_lines.extend([f"{k}: {v}" for k, v in trailer_items])
+            out_lines.append("")
+        click.echo("\n".join(out_lines).rstrip())
+        return
+
+    if format == "json":
+        import json
+        click.echo(json.dumps(commits, indent=2))
+    else:
+        for c in commits:
+            body = remove_git_trailers(c["body"]) or "(no message)"
+            files = ", ".join(c.get("files", []))
+            click.echo(f"Commit: {c['sha']}")
+            click.echo(f"Date: {c['date']}")
+            click.echo(f"Files: {files}")
+            click.echo(f"\n{body}\n")
+            click.echo("-" * 80)

git_history_extraction-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[project]
+name = "git-history-extraction"
+version = "0.1.0"
+description = "Extract and analyze git commit history with support for filtering by trailers, date ranges, and AI-powered summarization for changelogs"
+keywords = ["git", "changelog", "history", "commit", "trailers", "ai", "summarization", "openai", "gemini"]
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = ["click>=8.0"]
+authors = [{ name = "Michael Bianco", email = "mike@mikebian.co" }]
+urls = { "Repository" = "https://github.com/iloveitaly/git-history-extraction" }
+
+# additional packaging information: https://packaging.python.org/en/latest/specifications/core-metadata/#license
+[project.scripts]
+git-history-extraction = "git_history_extraction:main"
+
+[build-system]
+requires = ["uv_build>=0.8.11,<0.9.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+# avoids the src/ directory structure
+module-root = ""
+
+[dependency-groups]
+dev = ["pytest>=8.3.3"]
+